Box Classifications API

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

    used for content that is

    sensitive or under security

    restrictions.'
  x-box-tag: classifications
paths:
  /metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema:
    get:
      operationId: get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema
      summary: Box List all classifications
      tags:
      - Classifications
      x-box-tag: classifications
      x-box-sanitized: true
      description: 'Retrieves the classification metadata template and lists all the

        classifications available to this enterprise.


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

        URL explicitly, for example

        `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.'
      responses:
        '200':
          description: 'Returns 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/ClassificationTemplate'
        '400':
          description: Returned if any of the request parameters are not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returned when a template name is not correct. Please make sure

            the URL for the request is correct.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#add:
    put:
      operationId: put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#add
      summary: Box Add classification
      tags:
      - Classifications
      x-box-tag: classifications
      description: 'Adds one or more new classifications to the list of classifications

        available to the enterprise.


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

        URL explicitly, for example

        `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.'
      requestBody:
        content:
          application/json:
            schema:
              required:
              - items
              description: 'An array that contains one or more classifications to add to

                the enterprise''s list of classifications.'
              type: array
              items:
                type: object
                description: A single classification to add to the enterprise.
                required:
                - op
                - fieldKey
                - data
                properties:
                  op:
                    type: string
                    example: addEnumOption
                    description: 'The type of change to perform on the classification

                      object.'
                    enum:
                    - addEnumOption
                  fieldKey:
                    type: string
                    example: Box__Security__Classification__Key
                    description: "Defines classifications \navailable in the enterprise."
                    enum:
                    - Box__Security__Classification__Key
                  data:
                    type: object
                    required:
                    - key
                    description: The details of the classification to add.
                    properties:
                      key:
                        type: string
                        example: Sensitive
                        description: 'The label of the classification as shown in the web and

                          mobile interfaces. This is the only field required to

                          add a classification.'
                      staticConfig:
                        type: object
                        description: A static configuration for the classification.
                        properties:
                          classification:
                            type: object
                            description: Additional details for the classification.
                            properties:
                              classificationDefinition:
                                type: string
                                example: Sensitive information that must not be shared.
                                description: A longer description of the classification.
                              colorID:
                                type: integer
                                format: int64
                                example: 4
                                description: 'An internal Box identifier used to assign a color to

                                  a classification label.


                                  Mapping between a `colorID` and a color may change

                                  without notice. Currently, the color mappings are as

                                  follows.


                                  * `0`: Yellow

                                  * `1`: Orange

                                  * `2`: Watermelon red

                                  * `3`: Purple rain

                                  * `4`: Light blue

                                  * `5`: Dark blue

                                  * `6`: Light green

                                  * `7`: Gray'
      responses:
        '200':
          description: 'Returns the updated `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/ClassificationTemplate'
        '400':
          description: Returned if any of the request parameters are not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returned when a template name is not correct. Please make sure

            the URL for the request is correct.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#update:
    put:
      operationId: put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#update
      summary: Box Update classification
      tags:
      - Classifications
      x-box-tag: classifications
      x-box-sanitized: true
      description: 'Updates the labels and descriptions of one or more classifications

        available to the enterprise.


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

        URL explicitly, for example

        `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.'
      requestBody:
        content:
          application/json-patch+json:
            schema:
              description: An array that contains one or more classifications to update.
              type: array
              required:
              - items
              items:
                type: object
                description: A single classification to update.
                required:
                - op
                - fieldKey
                - enumOptionKey
                - data
                properties:
                  op:
                    type: string
                    example: editEnumOption
                    description: 'The type of change to perform on the classification

                      object.'
                    enum:
                    - editEnumOption
                  fieldKey:
                    type: string
                    example: Box__Security__Classification__Key
                    description: "Defines classifications \navailable in the enterprise."
                    enum:
                    - Box__Security__Classification__Key
                  enumOptionKey:
                    type: string
                    example: Sensitive
                    description: The original label of the classification to change.
                  data:
                    type: object
                    required:
                    - key
                    description: The details of the updated classification.
                    properties:
                      key:
                        type: string
                        example: Very Sensitive
                        description: 'A new label for the classification, as it will be

                          shown in the web and mobile interfaces.'
                      staticConfig:
                        type: object
                        description: A static configuration for the classification.
                        properties:
                          classification:
                            type: object
                            description: Additional details for the classification.
                            properties:
                              classificationDefinition:
                                type: string
                                example: Sensitive information that must not be shared.
                                description: A longer description of the classification.
                              colorID:
                                type: integer
                                format: int64
                                example: 4
                                description: 'An internal Box identifier used to assign a color to

                                  a classification label.


                                  Mapping between a `colorID` and a color may change

                                  without notice. Currently, the color mappings are as

                                  follows.


                                  * `0`: Yellow

                                  * `1`: Orange

                                  * `2`: Watermelon red

                                  * `3`: Purple rain

                                  * `4`: Light blue

                                  * `5`: Dark blue

                                  * `6`: Light green

                                  * `7`: Gray'
      responses:
        '200':
          description: 'Returns the updated `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/ClassificationTemplate'
        '400':
          description: Returned if any of the request parameters are not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returned when a template name is not correct. Please make sure

            the URL for the request is correct.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /metadata_templates/schema#classifications:
    post:
      operationId: post_metadata_templates_schema#classifications
      summary: Box Add initial classifications
      tags:
      - Classifications
      x-box-tag: classifications
      x-box-sanitized: true
      description: 'When an enterprise does not yet have any classifications, this API call

        initializes the classification template with an initial set of

        classifications.


        If an enterprise already has a classification, the template will already

        exist and instead an API call should be made to add additional

        classifications.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - scope
              - displayName
              - fields
              - templateKey
              properties:
                scope:
                  type: string
                  description: 'The scope in which to create the classifications. This should

                    be `enterprise` or `enterprise_{id}` where `id` is the unique

                    ID of the enterprise.'
                  example: enterprise
                  enum:
                  - enterprise
                templateKey:
                  type: string
                  example: securityClassification-6VMVochwUWo
                  description: Defines the list of metadata templates.
                  enum:
                  - securityClassification-6VMVochwUWo
                displayName:
                  type: string
                  description: 'The name of the

                    template as shown in web and mobile interfaces.'
                  example: Classification
                  enum:
                  - Classification
                hidden:
                  type: boolean
                  example: false
                  description: 'Determines if the classification template is

                    hidden or available on web and mobile

                    devices.'
                copyInstanceOnItemCopy:
                  type: boolean
                  example: false
                  description: 'Determines if classifications are

                    copied along when the file or folder is

                    copied.'
                fields:
                  type: array
                  description: 'The classification template requires exactly

                    one field, which holds

                    all the valid classification values.'
                  items:
                    required:
                    - type
                    - key
                    - displayName
                    - options
                    type: object
                    description: 'The `enum` field which holds all the valid classification

                      values.'
                    properties:
                      type:
                        type: string
                        example: enum
                        description: 'The type of the field

                          that is always enum.'
                        enum:
                        - enum
                      key:
                        type: string
                        example: Box__Security__Classification__Key
                        description: "Defines classifications \navailable in the enterprise."
                        enum:
                        - Box__Security__Classification__Key
                      displayName:
                        type: string
                        example: Classification
                        description: A display name for the classification.
                        enum:
                        - Classification
                      hidden:
                        type: boolean
                        example: false
                        description: 'Determines if the classification

                          template is

                          hidden or available on

                          web and mobile

                          devices.'
                      options:
                        type: array
                        description: 'The actual list of classifications that are present on

                          this template.'
                        items:
                          required:
                          - key
                          type: object
                          description: An individual classification.
                          properties:
                            key:
                              type: string
                              description: 'The display name and key this classification. This

                                will be show in the Box UI.'
                              example: Sensitive
                            staticConfig:
                              type: object
                              description: Additional information about the classification.
                              properties:
                                classification:
                                  type: object
                                  description: Additional information about the classification.
                                  properties:
                                    classificationDefinition:
                                      type: string
                                      example: Sensitive information
                                      description: A longer description of the classification.
                                    colorID:
                                      type: integer
                                      format: int64
                                      example: 4
                                      description: 'An identifier used to assign a color to

                                        a classification label.


                                        Mapping between a `colorID` and a color may

                                        change without notice. Currently, the color

                                        mappings are as follows.


                                        * `0`: Yellow

                                        * `1`: Orange

                                        * `2`: Watermelon red

                                        * `3`: Purple rain

                                        * `4`: Light blue

                                        * `5`: Dark blue

                                        * `6`: Light green

                                        * `7`: Gray'
      responses:
        '200':
          description: 'Returns a new `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/ClassificationTemplate'
        '400':
          description: Returned if any of the request parameters are not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returned when a template name is not correct. Please make sure

            the URL for the request is correct.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    ClassificationTemplate:
      title: Classification Template
      type: object
      x-box-resource-id: classification_template
      x-box-tag: classifications
      description: 'A metadata template that holds the security classifications

        defined by an enterprise.'
      required:
      - id
      - type
      - scope
      - displayName
      - fields
      - templateKey
      properties:
        id:
          type: string
          example: 58063d82-4128-7b43-bba9-92f706befcdf
          description: The ID of the classification template.
        type:
          type: string
          description: '`metadata_template`'
          example: metadata_template
          enum:
          - metadata_template
          nullable: false
        scope:
          type: string
          description: 'The scope of the classification template. This is in the format

            `enterprise_{id}` where the `id` is the enterprise ID.'
          example: enterprise_123456
        templateKey:
          type: string
          example: securityClassification-6VMVochwUWo
          description: '`securityClassification-6VMVochwUWo`'
          enum:
          - securityClassification-6VMVochwUWo
        displayName:
          type: string
          example: Classification
          description: The name of this template as shown in web and mobile interfaces.
          enum:
          - Classification
        hidden:
          type: boolean
          example: false
          description: 'Determines if the

            template is always available in web and mobile interfaces.'
        copyInstanceOnItemCopy:
          type: boolean
          example: true
          description: "Determines if \nclassifications are\ncopied along when the file or folder is\ncopied."
        fields:
          type: array
          maxItems: 1
          minItems: 1
          description: 'A list of fields for this classification template. This includes

            only one field, the `Box__Security__Classification__Key`, which defines

            the different classifications available in this enterprise.'
          items:
            type: object
            required:
            - id
            - type
            - key
            - displayName
            - options
            description: 'The metadata template field that represents the available

              classifications.'
            properties:
              id:
                type: string
                example: 822227e0-47a5-921b-88a8-494760b2e6d2
                description: The unique ID of the field.
              type:
                type: string
                example: enum
                description: The array item type.
                enum:
                - enum
              key:
                type: string
                example: Box__Security__Classification__Key
                description: "Defines classifications \navailable in the enterprise."
                enum:
                - Box__Security__Classification__Key
              displayName:
                type: string
                example: Classification
                description: '`Classification`'
                enum:
                - Classification
              hidden:
                type: boolean
                example: false
                description: Classifications are always visible to web and mobile users.
              options:
                type: array
                description: A list of classifications available in this enterprise.
                minItems: 1
                items:
                  required:
                  - key
                  - id
                  type: object
                  description: A single classification available in this enterprise.
                  properties:
                    id:
                      type: string
                      example: 46aea176-3483-4431-856c-6b5b13d1cc50
                      description: The unique ID of this classification.
                    key:
                      type: string
                      example: Sensitive
                      description: The display name and key for this classification.
                    staticConfig:
                      type: object
                      description: Additional information about the classification.
                      properties:
                        classification:
                          type: object
                          description: 'Additional information about the classification.


                            This is not an exclusive list of properties, and

                            more object fields might be returned. These fields

                            are used for internal Box Shield and Box Governance

                            purposes and no additional value must be derived from

                            these fields.'
                          properties:
                            classificationDefinition:
                              type: string
                              example: Sensitive information
                              description: A longer description of the classification.
                            colorID:
                              type: integer
                              format: int64
                              example: 4
                              description: 'An internal Box identifier used to assign a color to

                                a classification label.


                                Mapping between a `colorID` and a color may change

                                without notice. Currently, the color mappings are as

                                follows.


                                * `0`: Yellow

                                * `1`: Orange

                                * `2`: Watermelon red

                                * `3`: Purple rain

                                * `4`: Light blue

                                * `5`: Dark blue

                                * `6`: Light green

                                * `7`: Gray'
    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