Box Metadata Instances (Files) API

openapi: 3.1.0
info:
  title: Box Authorize Authorization Metadata Instances (Files) API
  description: Needs a description.
tags:
- name: Metadata Instances (Files)
  description: 'A metadata instance describes

    the relation between a template and a file,

    including the values that are assigned for every field.'
  x-box-tag: file_metadata
paths:
  /files/{file_id}/metadata:
    get:
      operationId: get_files_id_metadata
      summary: Box List metadata instances on file
      tags:
      - Metadata Instances (Files)
      x-box-tag: file_metadata
      x-box-sanitized: true
      description: Retrieves all metadata for a given file.
      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:
        '200':
          description: 'Returns all the metadata associated with a file.


            This API does not support pagination and will therefore always return

            all of the metadata associated to the file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metadatas'
        '403':
          description: Returned when the request parameters are not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: Returned when the user does not have access to the file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /files/{file_id}/metadata/{scope}/{template_key}:
    get:
      operationId: get_files_id_metadata_id_id
      summary: Box Get metadata instance on file
      tags:
      - Metadata Instances (Files)
      x-box-tag: file_metadata
      x-box-sanitized: true
      description: 'Retrieves the instance of a metadata template that has been applied to a

        file.'
      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
      - 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:
        '201':
          description: 'An instance of the metadata template that includes

            additional "key:value" pairs defined by the user or

            an application.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metadata--Full'
        '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_id_id
      summary: Box Create metadata instance on file
      tags:
      - Metadata Instances (Files)
      x-box-tag: file_metadata
      x-box-sanitized: true
      description: 'Applies an instance of a metadata template to a file.


        In most cases only values that are present in the metadata template

        will be accepted, except for the `global.properties` template which accepts

        any key-value pair.'
      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
      - 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:
            schema:
              type: object
              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
      responses:
        '201':
          description: 'Returns the instance of the template that was applied to the file,

            including the data that was applied to the template.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metadata--Full'
        '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_id_id
      summary: Box Update metadata instance on file
      tags:
      - Metadata Instances (Files)
      x-box-tag: file_metadata
      x-box-sanitized: true
      description: 'Updates a piece of metadata on a file.


        The metadata instance can only be updated if the template has already been

        applied to the file before. When editing metadata, only values that match

        the metadata template schema will be accepted.


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

        application of the operations, the metadata instance will not be changed.'
      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
      - 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

                instance.


                The changes are represented as a JSON array of

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

                  change to make to the metadata instance.'
                type: object
                properties:
                  op:
                    type: string
                    example: add
                    enum:
                    - add
                    - replace
                    - remove
                    - test
                    - move
                    - copy
                    description: 'The type of change to perform on the template. Some

                      of these are hazardous as they will change existing templates.'
                  path:
                    type: string
                    example: /currentState
                    description: 'The location in the metadata JSON object

                      to apply the changes to, in the format of a

                      [JSON-Pointer](https://tools.ietf.org/html/rfc6901).


                      The path must always be prefixed with a `/` to represent the root

                      of the template. The characters `~` and `/` are reserved

                      characters and must be escaped in the key.'
                  value:
                    type: string
                    example: reviewed
                    description: 'The value to be set or tested.


                      Required for `add`, `replace`, and `test` operations. For `add`,

                      if the value exists already the previous value will be overwritten

                      by the new value. For `replace`, the value must exist before

                      replacing.


                      For `test`, the existing value at the `path` location must match

                      the specified value.'
                  from:
                    type: string
                    example: /nextState
                    description: 'The location in the metadata JSON object to move or copy a value

                      from. Required for `move` or `copy` operations and must be in the

                      format of a [JSON-Pointer](https://tools.ietf.org/html/rfc6901).'
      responses:
        '200':
          description: 'Returns the updated metadata template instance, with the

            custom template data included.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metadata--Full'
        '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 objects.'
          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_id_id
      summary: Box Remove metadata instance from file
      tags:
      - Metadata Instances (Files)
      x-box-tag: file_metadata
      x-box-sanitized: true
      description: Deletes a piece of file metadata.
      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
      - 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 is

            successfully deleted.'
        '400':
          description: 'Returned when the request parameters are not valid. This may happen of the

            `scope` is not valid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returns an error when the file does not have an instance of the metadata

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

            file.


            * `instance_not_found` - An instance of the metadata template with the

            given `scope` and `templateKey` 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:
    Metadata:
      title: Metadata instance
      type: object
      x-box-resource-id: metadata
      x-box-tag: file_metadata
      x-box-variant: standard
      description: 'An instance of a metadata template, which has been applied to a file or

        folder.'
      allOf:
      - $ref: '#/components/schemas/Metadata--Base'
    Metadata--Full:
      title: Metadata instance (Full)
      type: object
      x-box-resource-id: metadata--full
      x-box-variant: full
      description: 'An instance of a metadata template, which has been applied to a file or

        folder.'
      allOf:
      - $ref: '#/components/schemas/Metadata'
      - properties:
          $canEdit:
            type: boolean
            example: true
            description: Whether the user can edit this metadata instance.
          $id:
            type: string
            format: uuid
            example: 01234500-12f1-1234-aa12-b1d234cb567e
            maxLength: 36
            description: A UUID to identify the metadata instance.
          $type:
            type: string
            example: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
            description: 'A unique identifier for the "type" of this instance. This is an

              internal system property and should not be used by a client

              application.'
          $typeVersion:
            type: integer
            example: 2
            description: 'The last-known version of the template of the object. This is an

              internal system property and should not be used by a client

              application.'
      - 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
    Metadatas:
      title: Metadata instances
      type: object
      x-box-resource-id: metadatas
      x-box-tag: file_metadata
      description: A list of metadata instances that have been applied to a file or folder.
      properties:
        entries:
          type: array
          description: A list of metadata instances, as applied to this file or folder.
          items:
            $ref: '#/components/schemas/Metadata'
        limit:
          description: The limit that was used for this page of results.
          example: 100
          type: integer
    Metadata--Base:
      title: Metadata instance (Base)
      type: object
      x-box-resource-id: metadata--base
      x-box-sanitized: true
      x-box-tag: file_metadata
      x-box-variants:
      - base
      - standard
      - full
      x-box-variant: base
      description: The base representation of a metadata instance.
      properties:
        $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: marketingCollateral
          description: The name of the template
        $scope:
          type: string
          example: enterprise_27335
          description: 'An ID for the scope in which this template

            has been applied. This will be `enterprise_{enterprise_id}` for templates

            defined for use in this enterprise, and `global` for general templates

            that are available to all enterprises using Box.'
        $version:
          type: integer
          example: 1
          description: 'The version of the metadata instance. This version starts at 0 and

            increases every time a user-defined property is modified.'
    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