Box Metadata Templates API

openapi: 3.1.0
info:
  version: "1.0"
  title: Box Authorize Authorization Metadata Templates API
  description: Needs a description.
tags:
- name: Metadata Templates
  description: 'A metadata template describes a reusable set

    of key/value pairs that can be assigned to a file.'
  x-box-tag: metadata_templates
paths:
  /metadata_templates:
    get:
      operationId: get_metadata_templates
      summary: Box Find metadata template by instance ID
      tags:
      - Metadata Templates
      x-box-tag: metadata_templates
      x-box-sanitized: true
      description: 'Finds a metadata template by searching for the ID of an instance of the

        template.'
      parameters:
      - name: metadata_instance_id
        description: The ID of an instance of the metadata template to find.
        example: 01234500-12f1-1234-aa12-b1d234cb567e
        in: query
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: 'Returns a list containing the 1 metadata template that matches the

            instance ID.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataTemplates'
        '400':
          description: Returned when the request parameters are not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /metadata_templates/{scope}/{template_key}/schema:
    get:
      operationId: get_metadata_templates_id_id_schema
      summary: Box Get metadata template by name
      tags:
      - Metadata Templates
      x-box-tag: metadata_templates
      x-box-sanitized: true
      description: 'Retrieves a metadata template by its `scope` and `templateKey` values.


        To find the `scope` and `templateKey` for a template, list all templates for

        an enterprise or globally, or list all templates applied to a file or folder.'
      parameters:
      - name: scope
        description: The scope of the metadata template
        example: global
        in: path
        required: true
        schema:
          type: string
          enum:
          - global
          - enterprise
      - name: template_key
        description: The name of the metadata template
        example: properties
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Returns the metadata template matching the `scope`

            and `template` name.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataTemplate'
        '400':
          description: "Returned if any of the request parameters are not valid.\n\n* `bad_request`: Often returned when the scope of the template is not\n  recognised. Please make sure to use either `enterprise` or `global` as\n  the `scope` value."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returned when a template with the given `scope` and `template_key` can not

            be found.'
          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_metadata_templates_id_id_schema
      tags:
      - Metadata Templates
      x-box-tag: metadata_templates
      x-box-sanitized: true
      summary: Box Update metadata template
      description: 'Updates a metadata template.


        The metadata template can only be updated if the template

        already exists.


        The update is applied atomically. If any errors occur during the

        application of the operations, the metadata template will not be changed.'
      parameters:
      - name: scope
        description: The scope of the metadata template
        example: global
        in: path
        required: true
        schema:
          type: string
          enum:
          - global
          - enterprise
      - name: template_key
        description: The name of the metadata template
        example: properties
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              description: 'A [JSON-Patch](https://tools.ietf.org/html/rfc6902)

                specification for the changes to make to the metadata

                template.


                The changes are represented as a JSON array of

                operation objects.'
              type: array
              items:
                title: A metadata template update operation
                description: 'A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a

                  change to make to the metadata instance.'
                type: object
                required:
                - op
                properties:
                  op:
                    type: string
                    example: addEnumOption
                    enum:
                    - editTemplate
                    - addField
                    - reorderFields
                    - addEnumOption
                    - reorderEnumOptions
                    - reorderMultiSelectOptions
                    - addMultiSelectOption
                    - editField
                    - removeField
                    - editEnumOption
                    - removeEnumOption
                    - editMultiSelectOption
                    - removeMultiSelectOption
                    description: 'The type of change to perform on the template. Some

                      of these are hazardous as they will change existing templates.'
                  data:
                    type: object
                    description: 'The data for the operation. This will vary depending on the

                      operation being performed.'
                    example:
                      name: Aaron Levie
                    additionalProperties:
                      allOf:
                      - {}
                      - example: Aaron Levie
                      - description: "A value for each of the fields that are present\non the metadata template.\nFor the `global.properties` template this can be\na list of zero or more fields,\nas this template allows for any generic key-value pairs \nto be stored stored in the template."
                      x-box-example-key: name
                  fieldKey:
                    type: string
                    example: category
                    description: 'For operations that affect a single field this defines the key of

                      the field that is affected.'
                  fieldKeys:
                    type: array
                    items:
                      type: string
                    example:
                    - category
                    - name
                    description: 'For operations that affect multiple fields this defines the keys

                      of the fields that are affected.'
                  enumOptionKey:
                    description: 'For operations that affect a single `enum` option this defines

                      the key of the option that is affected.'
                    type: string
                    example: option1
                  enumOptionKeys:
                    description: 'For operations that affect multiple `enum` options this defines

                      the keys of the options that are affected.'
                    type: array
                    items:
                      type: string
                    example:
                    - option1
                    - option2
                    - option3
                  multiSelectOptionKey:
                    description: 'For operations that affect a single multi select option this

                      defines the key of the option that is affected.'
                    type: string
                    example: option1
                  multiSelectOptionKeys:
                    description: 'For operations that affect multiple multi select options this

                      defines the keys of the options that are affected.'
                    type: array
                    items:
                      type: string
                    example:
                    - option1
                    - option2
                    - option3
      responses:
        '200':
          description: 'Returns the updated metadata template, with the

            custom template data included.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataTemplate'
        '400':
          description: The request body does not contain a valid metadata schema.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: 'The request body contains a scope that the user is not

            allowed to create templates for.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: The requested template could not be found
          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_metadata_templates_id_id_schema
      summary: Box Remove metadata template
      tags:
      - Metadata Templates
      x-box-tag: metadata_templates
      x-box-sanitized: true
      description: 'Delete a metadata template and its instances.

        This deletion is permanent and can not be reversed.'
      parameters:
      - name: scope
        description: The scope of the metadata template
        example: global
        in: path
        required: true
        schema:
          type: string
          enum:
          - global
          - enterprise
      - name: template_key
        description: The name of the metadata template
        example: properties
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 'Returns an empty response when the metadata

            template is successfully deleted.'
        '400':
          description: Request body does not contain a valid metadata schema.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: 'Request body contains a scope that the user is not allowed to

            create a template for.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /metadata_templates/{template_id}:
    get:
      operationId: get_metadata_templates_id
      summary: Box Get metadata template by ID
      tags:
      - Metadata Templates
      x-box-tag: metadata_templates
      x-box-sanitized: true
      description: Retrieves a metadata template by its ID.
      parameters:
      - name: template_id
        schema:
          type: string
        required: true
        in: path
        example: f7a9891f
        description: The ID of the template
      responses:
        '200':
          description: Returns the metadata template that matches the ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataTemplate'
        '400':
          description: "Returned if any of the request parameters are not valid.\n\n* `bad_request`: Often returned with a message when the ID of the template\n  is not recognised."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataTemplate'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /metadata_templates/global:
    get:
      operationId: get_metadata_templates_global
      summary: Box List all global metadata templates
      tags:
      - Metadata Templates
      x-box-tag: metadata_templates
      x-box-sanitized: true
      description: 'Used to retrieve all generic, global metadata templates available to all

        enterprises using Box.'
      parameters:
      - 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 all of the metadata templates available to all enterprises

            and their corresponding schema.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataTemplates'
        '400':
          description: Returned when the request parameters are not valid.
          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:
    get:
      operationId: get_metadata_templates_enterprise
      summary: Box List all metadata templates for enterprise
      tags:
      - Metadata Templates
      x-box-tag: metadata_templates
      x-box-sanitized: true
      description: 'Used to retrieve all metadata templates created to be used specifically within

        the user''s enterprise'
      parameters:
      - 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 all of the metadata templates within an enterprise

            and their corresponding schema.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataTemplates'
        '400':
          description: Returned when the request parameters are not valid.
          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:
    post:
      operationId: post_metadata_templates_schema
      summary: Box Create metadata template
      tags:
      - Metadata Templates
      description: 'Creates a new metadata template that can be applied to

        files and folders.'
      x-box-tag: metadata_templates
      x-box-requires-admin: true
      x-box-sanitized: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - scope
              - displayName
              properties:
                scope:
                  type: string
                  description: 'The scope of the metadata template to create. Applications can

                    only create templates for use within the authenticated user''s

                    enterprise.


                    This value needs to be set to `enterprise`, as `global` scopes can

                    not be created by applications.'
                  example: enterprise
                templateKey:
                  type: string
                  example: productInfo
                  description: 'A unique identifier for the template. This identifier needs to be

                    unique across the enterprise for which the metadata template is

                    being created.


                    When not provided, the API will create a unique `templateKey`

                    based on the value of the `displayName`.'
                  maxLength: 64
                  pattern: ^[a-zA-Z_][-a-zA-Z0-9_]*$
                displayName:
                  type: string
                  description: The display name of the template.
                  maxLength: 4096
                  example: Product Info
                hidden:
                  type: boolean
                  example: true
                  description: 'Defines if this template is visible in the Box web app UI, or if

                    it is purely intended for usage through the API.'
                  default: false
                fields:
                  type: array
                  description: 'An ordered list of template fields which are part of the template.

                    Each field can be a regular text field, date field, number field,

                    as well as a single or multi-select list.'
                  items:
                    title: Metadata Field (Write)
                    description: 'A field within a metadata template. Fields can be a basic text, date, or

                      number field, or a list of options.'
                    required:
                    - type
                    - key
                    - displayName
                    type: object
                    properties:
                      type:
                        type: string
                        example: string
                        description: 'The type of field. The basic fields are a `string` field for text, a

                          `float` field for numbers, and a `date` fields to present the user with a

                          date-time picker.


                          Additionally, metadata templates support an `enum` field for a basic list

                          of items, and ` multiSelect` field for a similar list of items where the

                          user can select more than one value.'
                        enum:
                        - string
                        - float
                        - date
                        - enum
                        - multiSelect
                      key:
                        type: string
                        example: category
                        description: 'A unique identifier for the field. The identifier must

                          be unique within the template to which it belongs.'
                        maxLength: 256
                      displayName:
                        type: string
                        example: Category
                        description: 'The display name of the field as it is shown to the user in the web and

                          mobile apps.'
                        maxLength: 4096
                      description:
                        type: string
                        example: The category
                        description: A description of the field. This is not shown to the user.
                        maxLength: 4096
                      hidden:
                        type: boolean
                        example: true
                        description: 'Whether this field is hidden in the UI for the user and can only be set

                          through the API instead.'
                      options:
                        description: 'A list of options for this field. This is used in combination with the

                          `enum` and `multiSelect` field types.'
                        type: array
                        items:
                          title: Metadata Option (Write)
                          type: object
                          description: 'An option for a Metadata Template Field.


                            Options only need to be provided for fields of type `enum` and `multiSelect`.

                            Options represent the value(s) a user can select for the field either through

                            the UI or through the API.'
                          required:
                          - key
                          properties:
                            key:
                              description: 'The text value of the option. This represents both the display name of the

                                option and the internal key used when updating templates.'
                              example: Category 1
                              type: string
                copyInstanceOnItemCopy:
                  type: boolean
                  description: 'Whether or not to copy any metadata attached to a file or folder

                    when it is copied. By default, metadata is not copied along with a

                    file or folder when it is copied.'
                  default: false
                  example: true
      responses:
        '201':
          description: The schema representing the metadata template created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataTemplate'
        '400':
          description: 'Returned if the request parameters or body is not valid.


            * `bad_request` when the body does not contain a valid request. In many

            cases this response will include extra details on what fields are missing.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: 'Returned when the user does not have the permission to create the metadata

            template. This can happen for a few reasons, most commonly when the user

            does not have (co-)admin permissions, or the application tries to create a

            template with the `global` scope.'
          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:
    get:
      operationId: get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema
      summary: Box List all classifications
      tags:
      - Metadata Templates
      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:
      - Metadata Templates
      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:
      - Metadata Templates
      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__Classificatio

# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/box-metadata-templates-api-openapi.yml