Box Classifications on Files API

openapi: 3.1.0
info:
  title: Box Authorize Authorization Classifications on Files API
  description: Needs a description.
tags:
- name: Classifications on Files
  description: 'Classification labels are

    used for files that are

    sensitive or under security

    restrictions.'
  x-box-tag: file_classifications
paths:
  /files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo:
    get:
      operationId: get_files_id_metadata_enterprise_securityClassification-6VMVochwUWo
      summary: Box Get classification on file
      tags:
      - Classifications on Files
      x-box-tag: file_classifications
      x-box-sanitized: true
      description: 'Retrieves the classification metadata instance that

        has been applied to a file.


        This API can also be called by including the enterprise ID in the

        URL explicitly, for example

        `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.'
      parameters:
      - name: file_id
        description: 'The unique identifier that represents 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'
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: 'Returns an instance of the `securityClassification` metadata

            template, which contains a `Box__Security__Classification__Key`

            field that lists all the classifications available to this

            enterprise.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Classification'
        '403':
          description: Returned when the request parameters are not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returned if the metadata template specified

            was not applied to this file or the user does not have access to the

            file.


            * `instance_not_found` - The metadata template was not applied to the

            file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '405':
          description: Returned when the method was not allowed.
          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_files_id_metadata_enterprise_securityClassification-6VMVochwUWo
      summary: Box Add classification to file
      tags:
      - Classifications on Files
      x-box-tag: file_classifications
      x-box-sanitized: true
      description: 'Adds a classification to a file by specifying the label of the

        classification to add.


        This API can also be called by including the enterprise ID in the

        URL explicitly, for example

        `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.'
      parameters:
      - name: file_id
        description: 'The unique identifier that represents 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'
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                Box__Security__Classification__Key:
                  type: string
                  description: 'The name of the classification to apply to this file.


                    To list the available classifications in an enterprise,

                    use the classification API to retrieve the

                    [classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)

                    which lists all available classification keys.'
                  example: Sensitive
      responses:
        '201':
          description: 'Returns the classification template instance

            that was applied to the file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Classification'
        '400':
          description: 'Returns an error when the request body is not valid.


            * `schema_validation_failed` - The request body contains a value for a for

            a field that either does not exist, or for which the value or type does

            not match the expected field type. An example might be an unknown option

            for an `enum` or `multiSelect` field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returns an error when the file or metadata template was not found.


            * `not_found` - The file could not be found, or the user does not have

            access to the file.

            * `instance_tuple_not_found` - The metadata template was not found.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '409':
          description: 'Returns an error when an instance of this metadata template is already

            present on the file.


            * `tuple_already_exists` - An instance of them metadata template already

            exists on the file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    put:
      operationId: put_files_id_metadata_enterprise_securityClassification-6VMVochwUWo
      summary: Box Update classification on file
      tags:
      - Classifications on Files
      x-box-tag: file_classifications
      x-box-sanitized: true
      description: 'Updates a classification on a file.


        The classification can only be updated if a classification has already been

        applied to the file before. When editing classifications, only values are

        defined for the enterprise will be accepted.'
      parameters:
      - name: file_id
        description: 'The unique identifier that represents 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'
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              required:
              - items
              description: 'A list containing the one change to make, to

                update the classification label.'
              type: array
              items:
                type: object
                description: 'The operation to perform on the classification

                  metadata template instance. In this case, it use

                  used to replace the value stored for the

                  `Box__Security__Classification__Key` field with a new

                  value.'
                required:
                - op
                - path
                - value
                properties:
                  op:
                    type: string
                    example: replace
                    description: '`replace`'
                    enum:
                    - replace
                  path:
                    type: string
                    example: /Box__Security__Classification__Key
                    description: "Defines classifications \navailable in the enterprise."
                    enum:
                    - /Box__Security__Classification__Key
                  value:
                    type: string
                    description: 'The name of the classification to apply to this file.


                      To list the available classifications in an enterprise,

                      use the classification API to retrieve the

                      [classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)

                      which lists all available classification keys.'
                    example: Sensitive
      responses:
        '200':
          description: Returns the updated classification metadata template instance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Classification'
        '400':
          description: 'Returns an error when the request body is not valid.


            * `bad_request` - The request body format is not an array of valid JSON

            Patch operations.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '500':
          description: 'Returns an error in some edge cases when the request body is not a valid

            array of JSON Patch items.'
          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_files_id_metadata_enterprise_securityClassification-6VMVochwUWo
      summary: Box Remove classification from file
      tags:
      - Classifications on Files
      x-box-tag: file_classifications
      x-box-sanitized: true
      description: 'Removes any classifications from a file.


        This API can also be called by including the enterprise ID in the

        URL explicitly, for example

        `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.'
      parameters:
      - name: file_id
        description: 'The unique identifier that represents 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'
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 'Returns an empty response when the classification is

            successfully deleted.'
        '400':
          description: Returned when the request parameters are not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returns an error when the file does not have any classification applied

            to it, or when the user does not have access to the

            file.


            * `instance_not_found` - An instance of the classification metadata

            template with the was not found on this file.

            * `not_found` - The file was not found, or the user does not have access

            to the file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '405':
          description: Returned when the method was not allowed.
          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
    Classification:
      title: Classification
      type: object
      x-box-resource-id: classification
      x-box-tag: classifications
      description: 'An instance of the classification metadata template, containing

        the classification applied to the file or folder.


        To get more details about the classification applied to an item,

        request the classification metadata template.'
      properties:
        Box__Security__Classification__Key:
          type: string
          example: Sensitive
          description: The name of the classification applied to the item.
        $parent:
          type: string
          example: folder_59449484661,
          description: 'The identifier of the item that this metadata instance

            has been attached to. This combines the `type` and the `id`

            of the parent in the form `{type}_{id}`.'
        $template:
          type: string
          example: securityClassification-6VMVochwUWo
          description: '`securityClassification-6VMVochwUWo`'
          enum:
          - securityClassification-6VMVochwUWo
        $scope:
          type: string
          example: enterprise_27335
          description: 'The scope of the enterprise that this classification has been

            applied for.


            This will be in the format `enterprise_{enterprise_id}`.'
        $version:
          type: integer
          example: 1
          description: 'The version of the metadata instance. This version starts at 0 and

            increases every time a classification is updated.'
        $type:
          type: string
          example: securityClassification-6VMVochwUWo-fd31537a-0f95-4d86-9f2b-5974a29978f8
          description: 'The unique ID of this classification instance. This will be include

            the name of the classification template and a unique ID.'
        $typeVersion:
          type: number
          example: 5
          description: 'The version of the metadata template. This version starts at 0 and

            increases every time the template is updated. This is mostly for internal

            use.'
        $canEdit:
          type: boolean
          example: true
          description: Whether an end user can change the classification.