Box Retention Policy Assignments API

openapi: 3.1.0
info:
  title: Box Retention Policy Assignments API
  description: Needs a description.
paths:
  /retention_policy_assignments:
    post:
      operationId: post_retention_policy_assignments
      summary: Box Assign retention policy
      tags:
        - Retention Policy Assignments
      x-box-tag: retention_policy_assignments
      description: Assigns a retention policy to an item.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - policy_id
                - assign_to
              properties:
                policy_id:
                  type: string
                  description: The ID of the retention policy to assign
                  example: '173463'
                assign_to:
                  type: object
                  description: The item to assign the policy to
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      description: The type of item to assign the policy to.
                      example: metadata_template
                      enum:
                        - enterprise
                        - folder
                        - metadata_template
                    id:
                      type: string
                      nullable: true
                      description: |-
                        The ID of item to assign the policy to.
                        Set to `null` or omit when `type` is set to
                        `enterprise`.
                      example: '6564564'
                filter_fields:
                  type: array
                  description: >-
                    If the `assign_to` type is `metadata_template`,

                    then optionally add the `filter_fields` parameter which will

                    require an array of objects with a field entry and a value
                    entry.

                    Currently only one object of `field` and `value` is
                    supported.
                  items:
                    type: object
                    properties:
                      field:
                        type: string
                        description: The metadata attribute key id.
                        example: a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4
                      value:
                        type: string
                        description: |-
                          The metadata attribute field id. For value, only
                          enum and multiselect types are supported.
                        example: 0c27b756-0p87-4fe0-a43a-59fb661ccc4e
                start_date_field:
                  description: |-
                    The date the retention policy assignment begins.

                    If the `assigned_to` type is `metadata_template`,
                    this field can be a date field's metadata attribute key id.
                  type: string
                  example: upload_date
      responses:
        '201':
          description: Returns a new retention policy assignment object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetentionPolicyAssignment'
        '400':
          description: >-
            Returns an error if an `id` is specified while assigning the

            retention policy to an enterprise.


            Returns an error if `start_date_field` is present but
            `assign_to.type`

            is not `metadata_template`


            Returns an error if `start_date_field` is present, but belongs to a

            different metadata template than the one specified in `assign_to.id`


            Returns an error if `start_date_field` is present, but the

            `retention_policy` has a `retention_length` of "indefinite"


            Returns an error if `start_date_field` is present, but cannot be
            resolved

            to a valid metadata date field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: >-
            Returns an error if no retention policy with the given `policy_id`
            exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '409':
          description: >-
            Returns an error if a retention policy of equal or greater length
            has

            already been assigned to this item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /retention_policy_assignments/{retention_policy_assignment_id}:
    get:
      operationId: get_retention_policy_assignments_id
      summary: Box Get retention policy assignment
      tags:
        - Retention Policy Assignments
      x-box-tag: retention_policy_assignments
      description: Retrieves a retention policy assignment
      parameters:
        - name: retention_policy_assignment_id
          description: The ID of the retention policy assignment.
          example: '1233123'
          in: path
          required: true
          schema:
            type: string
        - name: fields
          description: |-
            A comma-separated list of attributes to include in the
            response. This can be used to request fields that are
            not normally returned in a standard response.

            Be aware that specifying this parameter will have the
            effect that none of the standard fields are returned in
            the response unless explicitly specified, instead only
            fields for the mini representation are returned, additional
            to the fields requested.
          in: query
          example:
            - id
            - type
            - name
          required: false
          explode: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Returns the retention policy assignment object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetentionPolicyAssignment'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    delete:
      operationId: delete_retention_policy_assignments_id
      summary: Box Remove retention policy assignment
      tags:
        - Retention Policy Assignments
      x-box-tag: retention_policy_assignments
      description: |-
        Removes a retention policy assignment
        applied to content.
      parameters:
        - name: retention_policy_assignment_id
          description: The ID of the retention policy assignment.
          example: '1233123'
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: |-
            Returns an empty response when the policy assignment
            is successfully deleted.
        '403':
          description: |-
            Returns an error when the assignment relates to
            a retention policy that cannot be modified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: |-
            Returns an error when the retention policy
            assignment does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /retention_policy_assignments/{retention_policy_assignment_id}/files_under_retention:
    get:
      operationId: get_retention_policy_assignments_id_files_under_retention
      summary: Box Get files under retention
      tags:
        - Retention Policy Assignments
      x-box-tag: retention_policy_assignments
      description: >-
        Returns a list of files under retention for a retention policy
        assignment.
      parameters:
        - name: retention_policy_assignment_id
          description: The ID of the retention policy assignment.
          example: '1233123'
          in: path
          required: true
          schema:
            type: string
        - 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: limit
          description: The maximum number of items to return per page.
          in: query
          required: false
          example: 1000
          schema:
            type: integer
            format: int64
            maximum: 1000
      responses:
        '200':
          description: |-
            Returns a list of files under retention that are associated with the
            specified retention policy assignment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilesUnderRetention'
        '400':
          description: >-
            Returns an error if `retention_policy_assignment_id` is not
            specified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /retention_policy_assignments/{retention_policy_assignment_id}/file_versions_under_retention:
    get:
      operationId: get_retention_policy_assignments_id_file_versions_under_retention
      summary: Box Get file versions under retention
      tags:
        - Retention Policy Assignments
      x-box-tag: retention_policy_assignments
      description: |-
        Returns a list of file versions under retention for a retention policy
        assignment.
      parameters:
        - name: retention_policy_assignment_id
          description: The ID of the retention policy assignment.
          example: '1233123'
          in: path
          required: true
          schema:
            type: string
        - 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: limit
          description: The maximum number of items to return per page.
          in: query
          required: false
          example: 1000
          schema:
            type: integer
            format: int64
            maximum: 1000
      responses:
        '200':
          description: >-
            Returns a list of file versions under retention that are associated
            with

            the specified retention policy assignment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilesUnderRetention'
        '400':
          description: >-
            Returns an error if `retention_policy_assignment_id` is not
            specified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
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
          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
    RetentionPolicyAssignment:
      title: Retention policy assignment
      type: object
      x-box-resource-id: retention_policy_assignment
      x-box-tag: retention_policy_assignments
      description: |-
        A retention assignment represents a rule specifying
        the files a retention policy retains.
        Assignments can retain files based on their folder or metadata,
        or hold all files in the enterprise.
      required:
        - id
        - type
      properties:
        id:
          type: string
          description: The unique identifier for a retention policy assignment.
          example: '11446498'
        type:
          type: string
          description: '`retention_policy_assignment`'
          example: retention_policy_assignment
          enum:
            - retention_policy_assignment
        retention_policy:
          allOf:
            - $ref: '#/components/schemas/RetentionPolicy--Mini'
            - description: |-
                A mini representation of a retention policy object
                that has been assigned to the content.
        assigned_to:
          type: object
          description: |-
            The `type` and `id` of the content that is under
            retention. The `type` can either be `folder`
            `enterprise`, or `metadata_template`.
          properties:
            id:
              type: string
              nullable: true
              example: a983f69f-e85f-4ph4-9f46-4afdf9c1af65
              description: |-
                The ID of the folder, enterprise, or metadata template
                the policy is assigned to.
                Set to null or omit when type is set to enterprise.
            type:
              type: string
              example: metadata_template
              description: The type of resource the policy is assigned to.
              enum:
                - folder
                - enterprise
                - metadata_template
        filter_fields:
          type: array
          nullable: true
          description: >-
            An array of field objects. Values are only returned if the
            `assigned_to`

            type is `metadata_template`. Otherwise, the array is blank.
          items:
            type: object
            nullable: true
            properties:
              field:
                type: string
                nullable: true
                description: The metadata attribute key id.
                example: a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4
              value:
                type: string
                nullable: true
                description: |-
                  The metadata attribute field id. For value, only
                  enum and multiselect types are supported.
                example: 0c27b756-0p87-4fe0-a43a-59fb661ccc4e
        assigned_by:
          allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: |-
                A mini user object representing the user that
                created the retention policy assignment.
        assigned_at:
          type: string
          format: date-time
          description: |-
            When the retention policy assignment object was
            created.
          example: '2012-12-12T10:53:43-08:00'
        start_date_field:
          type: string
          description: |-
            The date the retention policy assignment begins.
            If the `assigned_to` type is `metadata_template`,
            this field can be a date field's metadata attribute key id.
          example: upload_date
    FilesUnderRetention:
      title: Files under retention
      type: object
      x-box-resource-id: files_under_retention
      x-box-tag: retention_policy_assignments
      description: A list of files under retention.
      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 files
              items:
                $ref: '#/components/schemas/File--Mini'
tags:
  - name: Retention Policy Assignments