openapi: 3.1.0
info:
  title: Box Authorize Authorization Retention Policy Assignments API
  description: Needs a description.
tags:
- name: Retention Policy Assignments
  description: 'A Retention Policy Assignment is a relation

    between a policy and folder or enterprise.

    Creating an assignment puts a retention on

    all the file versions that belong to that folder or enterprise.'
  x-box-tag: retention_policy_assignments
paths:
  /retention_policies/{retention_policy_id}/assignments:
    get:
      operationId: get_retention_policies_id_assignments
      summary: Box List retention policy assignments
      tags:
      - Retention Policy Assignments
      x-box-tag: retention_policy_assignments
      description: 'Returns a list of all retention policy assignments associated with a specified

        retention policy.'
      parameters:
      - name: retention_policy_id
        description: The ID of the retention policy.
        example: '982312'
        in: path
        required: true
        schema:
          type: string
      - name: type
        description: The type of the retention policy assignment to retrieve.
        in: query
        required: false
        example: metadata_template
        schema:
          type: string
          enum:
          - folder
          - enterprise
          - metadata_template
      - 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
      - name: marker
        description: 'Defines the position marker at which to begin returning results. This is

          used when paginating using marker-based pagination.'
        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 the retention policy assignments associated with the

            specified retention policy.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetentionPolicyAssignments'
        '400':
          description: Returns an error if an unknown `type` is 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:
    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:
    User--Base:
      title: User (Base)
      type: object
      x-box-resource-id: user--base
      x-box-tag: users
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'A mini representation of a user, used when

        nested within another resource.'
      required:
      - type
      - id
      properties:
        id:
          type: string
          description: The unique identifier for this user
          example: '11446498'
        type:
          type: string
          description: '`user`'
          example: user
          nullable: false
          enum:
          - user
    File--Base:
      title: File (Base)
      type: object
      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
      nullable: true
      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
          nullable: false
          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
          example: '1'
          nullable: true
          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
          nullable: false
    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'
    User--Mini:
      title: User (Mini)
      type: object
      x-box-resource-id: user--mini
      x-box-variant: mini
      description: 'A mini representation of a user, as can be returned when nested within other

        resources.'
      allOf:
      - $ref: '#/components/schemas/User--Base'
      - properties:
          name:
            type: string
            description: The display name of this user
            example: Aaron Levie
            maxLength: 50
            nullable: false
          login:
            type: string
            format: email
            description: The primary email address of this user
            example: ceo@example.com
            nullable: false
    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
      x-box-resource-id: file--mini
      x-box-variant: mini
      description: 'A mini representation of a file, used when

        nested under another resource.'
      nullable: true
      allOf:
      - $ref: '#/components/schemas/File--Base'
      - properties:
          sequence_id:
            allOf:
            - type: string
              example: '3'
              nullable: true
              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.'
            - nullable: false
          name:
            type: string
            description: The name of the file
            example: Contract.pdf
          sha1:
            type: string
            format: digest
            nullable: false
            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.
    RetentionPolicy--Base:
      title: Retention policy (Base)
      type: object
      x-box-resource-id: retention_policy--base
      x-box-tag: retention_policies
      x-box-variants:
      - base
      - mini
      - standard
      x-box-variant: base
      description: A base representation of a retention policy.
      required:
      - id
      - type
      properties:
        id:
          type: string
          nullable: false
          description: The unique identifier that represents a retention policy.
          example: '12345'
        type:
          type: string
          description: '`retention_policy`'
          example: retention_policy
          enum:
          - retention_policy
          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
    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
          nullable: false
          description: The unique identifier that represent a file version.
          example: '12345'
        type:
          type: string
          description: '`file_version`'
          example: file_version
          enum:
          - file_version
          nullable: false
    RetentionPolicyAssignments:
      title: Retention policy assignments
      type: object
      x-box-resource-id: retention_policy_assignments
      x-box-tag: retention_policy_assignments
      description: A list of retention policy assignments.
      allOf:
      - properties:
          entries:
            type: array
            description: A list of retention policy assignments
            items:
              $ref: '#/components/schemas/RetentionPolicyAssignment'
      - 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
    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
    RetentionPolicy--Mini:
      title: Retention policy (Mini)
      type: object
      x-box-resource-id: retention_policy--mini
      x-box-variant: mini
      description: 'A mini representation of a retention policy, used when

        nested within another resource.'
      allOf:
      - $ref: '#/components/schemas/RetentionPolicy--Base'
      - properties:
          policy_name:
            type: string
            description: The name given to the retention policy.
            example: Some Policy Name
          retention_length:
            type: string
            format: int32
            example: '365'
            minimum: 1
            description: 'The length of the retention policy. This value

              specifies the duration in days that the retention

              policy will be active for after being assigned to

              content.  If the policy has a `policy_type` of

              `indefinite`, the `retention_length` will also be

              `indefinite`.'
          disposition_action:
            type: string
            example: permanently_delete
            description: 'The disposition action of the retention policy.

              This action can be `permanently_delete`, which

              will cause the content retained by the policy

              to be permanently deleted, or `remove_retention`,

              which will lift the retention policy from the content,

              allowing it to be deleted by users,

              once the retention policy has expired.'
            enum:
            - permanently_delete
            - remove_retention