Box Uploads API

openapi: 3.1.0
info:
  title: Box Authorize Authorization Uploads API
  description: Needs a description.
tags:
- name: Uploads
  description: 'The direct file upload API supports files

    up to 50MB in size and sends all

    the binary data to the Box API in 1 API request.'
  x-box-tag: uploads
paths:
  /files/{file_id}/content:
    post:
      operationId: post_files_id_content
      tags:
      - Uploads
      x-box-tag: uploads
      summary: Box Upload file version
      description: 'Update a file''s content. For file sizes over 50MB we recommend

        using the Chunk Upload APIs.


        # Request body order


        The `attributes` part of the body must come **before** the

        `file` part. Requests that do not follow this format when

        uploading the file will receive a HTTP `400` error with a

        `metadata_after_file_contents` error code.'
      servers:
      - url: https://upload.box.com/api/2.0
        description: Server for file uploads
      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: if-match
        description: 'Ensures this item hasn''t recently changed before

          making changes.


          Pass in the item''s last observed `etag` value

          into this header and the endpoint will fail

          with a `412 Precondition Failed` if it

          has changed since.'
        in: header
        required: false
        example: '1'
        schema:
          type: string
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: content-md5
        required: false
        schema:
          type: string
        example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
        in: header
        description: 'An optional header containing the SHA1 hash of the file to

          ensure that the file was not corrupted in transit.'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - attributes
              - file
              properties:
                attributes:
                  description: "The additional attributes of the file being uploaded. Mainly the\nname and the parent folder. These attributes are part of the multi\npart request body and are in JSON format.\n\n<Message warning>\n\n  The `attributes` part of the body must come **before** the\n  `file` part. Requests that do not follow this format when\n  uploading the file will receive a HTTP `400` error with a\n  `metadata_after_file_contents` error code.\n\n</Message>"
                  type: object
                  required:
                  - name
                  properties:
                    name:
                      type: string
                      description: 'An optional new name for the file. If specified, the file

                        will be renamed when the new version is uploaded.'
                      example: Photo 2.0.png
                    content_modified_at:
                      type: string
                      format: date-time
                      example: '2012-12-12T10:53:43-08:00'
                      description: 'Defines the time the file was last modified at.


                        If not set, the upload time will be used.'
                file:
                  type: string
                  format: binary
                  description: "The content of the file to upload to Box.\n\n<Message warning>\n\n  The `attributes` part of the body must come **before** the\n  `file` part. Requests that do not follow this format when\n  uploading the file will receive a HTTP `400` error with a\n  `metadata_after_file_contents` error code.\n\n</Message>"
      responses:
        '200':
          description: Returns the new file object in a list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Files'
        '412':
          description: 'Returns an error when the `If-Match` header does not match

            the current `etag` value of the file. This indicates that the file

            has changed since it was last requested.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /files/content:
    post:
      operationId: post_files_content
      tags:
      - Uploads
      x-box-tag: uploads
      summary: Box Upload file
      description: 'Uploads a small file to Box. For file sizes over 50MB we recommend

        using the Chunk Upload APIs.


        # Request body order


        The `attributes` part of the body must come **before** the

        `file` part. Requests that do not follow this format when

        uploading the file will receive a HTTP `400` error with a

        `metadata_after_file_contents` error code.'
      servers:
      - url: https://upload.box.com/api/2.0
        description: Server for file uploads
      parameters:
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: content-md5
        required: false
        schema:
          type: string
        example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
        in: header
        description: 'An optional header containing the SHA1 hash of the file to

          ensure that the file was not corrupted in transit.'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - attributes
              - file
              properties:
                attributes:
                  description: "The additional attributes of the file being uploaded. Mainly the\nname and the parent folder. These attributes are part of the multi\npart request body and are in JSON format.\n\n<Message warning>\n\n  The `attributes` part of the body must come **before** the\n  `file` part. Requests that do not follow this format when\n  uploading the file will receive a HTTP `400` error with a\n  `metadata_after_file_contents` error code.\n\n</Message>"
                  type: object
                  required:
                  - name
                  - parent
                  properties:
                    name:
                      type: string
                      description: The name of the file
                      example: Photo.png
                    parent:
                      type: object
                      description: The parent folder to upload the file to
                      required:
                      - id
                      properties:
                        id:
                          type: string
                          example: '124132'
                          description: 'The id of the parent folder. Use

                            `0` for the user''s root folder.'
                    content_created_at:
                      type: string
                      format: date-time
                      example: '2012-12-12T10:53:43-08:00'
                      description: 'Defines the time the file was originally created at.


                        If not set, the upload time will be used.'
                    content_modified_at:
                      type: string
                      format: date-time
                      example: '2012-12-12T10:53:43-08:00'
                      description: 'Defines the time the file was last modified at.


                        If not set, the upload time will be used.'
                file:
                  type: string
                  format: binary
                  description: "The content of the file to upload to Box.\n\n<Message warning>\n\n  The `attributes` part of the body must come **before** the\n  `file` part. Requests that do not follow this format when\n  uploading the file will receive a HTTP `400` error with a\n  `metadata_after_file_contents` error code.\n\n</Message>"
      responses:
        '201':
          description: Returns the new file object in a list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Files'
        '400':
          description: "Returns an error if some of the parameters are missing or\nnot valid.\n* `bad_request` when a parameter is missing or incorrect.\n* `item_name_too_long` when the folder name is too long.\n* `item_name_invalid` when the folder name contains\n  non-valid characters."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returns an error if the parent folder

            does not exist or if the user

            is not authorized to access the parent folder.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '409':
          description: 'Returns an error if the file already exists,

            or the account has run out of disk space.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    Folder--Base:
      title: Folder (Base)
      type: object
      x-box-resource-id: folder--base
      x-box-sanitized: true
      x-box-tag: folders
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'The bare basic representation of a folder, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          nullable: false
          description: 'The unique identifier that represent a folder.


            The ID for any folder can be determined

            by visiting a folder in the web application

            and copying the ID from the URL. For example,

            for the URL `https://*.app.box.com/folders/123`

            the `folder_id` is `123`.'
          example: '12345'
        etag:
          type: string
          nullable: true
          example: '1'
          description: 'The HTTP `etag` of this folder. This can be used within some API

            endpoints in the `If-Match` and `If-None-Match` headers to only

            perform changes on the folder if (no) changes have happened.'
        type:
          type: string
          description: '`folder`'
          example: folder
          enum:
          - folder
          nullable: false
    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'
    File:
      title: File
      type: object
      x-box-resource-id: file
      x-box-variant: standard
      description: 'A standard representation of a file, as returned from any

        file API endpoints by default'
      allOf:
      - $ref: '#/components/schemas/File--Mini'
      - properties:
          description:
            type: string
            nullable: false
            description: The optional description of this file
            maxLength: 256
            example: Contract for Q1 renewal
          size:
            type: integer
            nullable: false
            description: 'The file size in bytes. Be careful parsing this integer as it can

              get very large and cause an integer overflow.'
            example: 629644
          path_collection:
            allOf:
            - title: Path collection
              description: A list of parent folders for an item.
              type: object
              required:
              - total_count
              - entries
              properties:
                total_count:
                  description: The number of folders in this list.
                  example: 1
                  type: integer
                  format: int64
                  nullable: false
                entries:
                  type: array
                  description: The parent folders for this item
                  nullable: false
                  items:
                    $ref: '#/components/schemas/Folder--Mini'
            - description: 'The tree of folders that this file is contained in,

                starting at the root.'
            - nullable: false
          created_at:
            type: string
            format: date-time
            nullable: false
            description: The date and time when the file was created on Box.
            example: '2012-12-12T10:53:43-08:00'
          modified_at:
            type: string
            format: date-time
            nullable: false
            description: The date and time when the file was last updated on Box.
            example: '2012-12-12T10:53:43-08:00'
          trashed_at:
            type: string
            format: date-time
            description: The time at which this file was put in the trash.
            example: '2012-12-12T10:53:43-08:00'
            nullable: true
          purged_at:
            type: string
            format: date-time
            description: 'The time at which this file is expected to be purged

              from the trash.'
            example: '2012-12-12T10:53:43-08:00'
            nullable: true
          content_created_at:
            type: string
            format: date-time
            nullable: true
            description: 'The date and time at which this file was originally

              created, which might be before it was uploaded to Box.'
            example: '2012-12-12T10:53:43-08:00'
          content_modified_at:
            type: string
            format: date-time
            nullable: true
            description: 'The date and time at which this file was last updated,

              which might be before it was uploaded to Box.'
            example: '2012-12-12T10:53:43-08:00'
          created_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who created this file
          modified_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who last modified this file
            - nullable: false
          owned_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who owns this file
            - nullable: false
          shared_link:
            allOf:
            - title: Shared link
              description: 'Shared links provide direct, read-only access to files or folder on Box.


                Shared links with open access level allow anyone with the URL

                to access the item, while shared links with company or collaborators access

                levels can only be accessed by appropriately authenticated Box users.'
              type: object
              required:
              - url
              - accessed
              - effective_access
              - effective_permission
              - is_password_enabled
              - download_count
              - preview_count
              properties:
                url:
                  type: string
                  format: url
                  description: 'The URL that can be used to access the item on Box.


                    This URL will display the item in Box''s preview UI where the file

                    can be downloaded if allowed.


                    This URL will continue to work even when a custom `vanity_url`

                    has been set for this shared link.'
                  example: https://www.box.com/s/vspke7y05sb214wjokpk
                  nullable: false
                download_url:
                  type: string
                  format: url
                  x-box-premium-feature: true
                  description: 'A URL that can be used to download the file. This URL can be used in

                    a browser to download the file. This URL includes the file

                    extension so that the file will be saved with the right file type.


                    This property will be `null` for folders.'
                  example: https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg
                  nullable: true
                vanity_url:
                  type: string
                  format: url
                  description: 'The "Custom URL" that can also be used to preview the item on Box.  Custom

                    URLs can only be created or modified in the Box Web application.'
                  example: https://acme.app.box.com/v/my_url/
                  nullable: true
                vanity_name:
                  type: string
                  description: The custom name of a shared link, as used in the `vanity_url` field.
                  example: my_url
                  nullable: true
                access:
                  type: string
                  description: "The access level for this shared link.\n\n* `open` - provides access to this item to anyone with this link\n* `company` - only provides access to this item to people the same company\n* `collaborators` - only provides access to this item to people who are\n   collaborators on this item\n\nIf this field is omitted when creating the shared link, the access level\nwill be set to the default access level specified by the enterprise admin."
                  enum:
                  - open
                  - company
                  - collaborators
                  example: open
                  nullable: false
                effective_access:
                  type: string
                  description: 'The effective access level for the shared link. This can be a more

                    restrictive access level than the value in the `access` field when the

                    enterprise settings restrict the allowed access levels.'
                  enum:
                  - open
                  - company
                  - collaborators
                  example: company
                  nullable: false
                effective_permission:
                  type: string
                  description: 'The effective permissions for this shared link.

                    These result in the more restrictive combination of

                    the share link permissions and the item permissions set

                    by the administrator, the owner, and any ancestor item

                    such as a folder.'
                  enum:
                  - can_edit
                  - can_download
                  - can_preview
                  - no_access
                  example: can_download
                  nullable: false
                unshared_at:
                  type: string
                  format: date-time
                  description: 'The date and time when this link will be unshared. This field can only be

                    set by users with paid accounts.'
                  example: '2018-04-13T13:53:23-07:00'
                  nullable: true
                is_password_enabled:
                  type: boolean
                  description: Defines if the shared link requires a password to access the item.
                  example: true
                  nullable: false
                permissions:
                  type: object
                  description: 'Defines if this link allows a user to preview, edit, and download an item.

                    These permissions refer to the shared link only and

                    do not supersede permissions applied to the item itself.'
                  required:
                  - can_download
                  - can_preview
                  - can_edit
                  properties:
                    can_download:
                      type: boolean
                      example: true
                      nullable: false
                      description: 'Defines if the shared link allows for the item to be downloaded. For

                        shared links on folders, this also applies to any items in the folder.


                        This value can be set to `true` when the effective access level is

                        set to `open` or `company`, not `collaborators`.'
                    can_preview:
                      type: boolean
                      example: true
                      nullable: false
                      description: 'Defines if the shared link allows for the item to be previewed.


                        This value is always `true`. For shared links on folders this also

                        applies to any items in the folder.'
                    can_edit:
                      type: boolean
                      example: false
                      nullable: false
                      description: 'Defines if the shared link allows for the item to be edited.


                        This value can only be `true` if `can_download` is also `true` and if

                        the item has a type of `file`.'
                download_count:
                  type: integer
                  example: 3
                  description: The number of times this item has been downloaded.
                  nullable: false
                preview_count:
                  type: integer
                  example: 3
                  description: The number of times this item has been previewed.
                  nullable: false
            - description: 'The shared link for this file. This will be

                `null` if no shared link has been created for this

                file.'
            - nullable: true
          parent:
            allOf:
            - $ref: '#/components/schemas/Folder--Mini'
            - description: The folder that this file is located within.
            nullable: true
          item_status:
            type: string
            description: 'Defines if this item has been deleted or not.


              * `active` when the item has is not in the trash

              * `trashed` when the item has been moved to the trash but not deleted

              * `deleted` when the item has been permanently deleted.'
            enum:
            - active
            - trashed
            - deleted
            nullable: false
            example: active
    Folder--Mini:
      title: Folder (Mini)
      type: object
      x-box-resource-id: folder--mini
      x-box-variant: mini
      description: 'A mini representation of a file version, used when

        nested under another resource.'
      allOf:
      - $ref: '#/components/schemas/Folder--Base'
      - properties:
          sequence_id:
            allOf:
            - type: string
              example: '3'
              nullable: true
              description: 'A numeric identifier that represents the most recent user event

                that has been applied to this item.


                This can be used in combination with the `GET /events`-endpoint

                to filter out user events that would have occurred before this

                identifier was read.


                An example would be where a Box Drive-like application

                would fetch an item via the API, and then listen to incoming

                user events for changes to the item. The application would

                ignore any user events where the `sequence_id` in the event

                is smaller than or equal to the `sequence_id` in the originally

                fetched resource.'
            - nullable: false
          name:
            type: string
            description: The name of the folder.
            example: Contracts
            nullable: false
    Files:
      title: Files
      type: object
      x-box-resource-id: files
      x-box-tag: files
      description: A list of files
      properties:
        total_count:
          description: The number of files.
          example: 1
          type: integer
          format: int64
        entries:
          type: array
          description: A list of files
          items:
            $ref: '#/components/schemas/File--Full'
    File--Base:
      title: File (Base)
      type: object
      x-box-resource-id: file--base
      x-box-sanitized: true
      x-box-tag: files
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      nullable: true
      description: 'The bare basic representation of a file, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          nullable: false
          description: 'The unique identifier that represent a file.


            The ID for any file can be determined

            by visiting a file in the web application

            and copying the ID from the URL. For example,

            for the URL `https://*.app.box.com/files/123`

            the `file_id` is `123`.'
          example: '12345'
        etag:
          type: string
          example: '1'
          nullable: true
          description: 'The HTTP `etag` of this file. This can be used within some API

            endpoints in the `If-Match` and `If-None-Match` headers to only

            perform changes on the file if (no) changes have happened.'
        type:
          type: string
          description: '`file`'
          example: file
          enum:
          - file
          nullable: false
    User--Base:
      title: User (Base)
      type: object
      x-box-resource-id: user--base
      x-box-tag: users
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'A mini representation of a user, used when

        nested within another resource.'
      required:
      - type
      - id
      properties:
        id:
          type: string
          description: The unique identifier for this user
          example: '11446498'
        type:
          type: string
          description: '`user`'
          example: user
          nullable: false
          enum:
          - user
    FileOrFolderScope:
      title: File or folder scope
      type: object
      description: A relation between a resource (file or folder) and the scopes for which the resource can be accessed
      properties:
        scope:
          type: string
          description: The scopes for the resource access
          example: item_download
          enum:
          - annotation_edit
          - annotation_view_all
          - annotation_view_self
          - base_explorer
          - base_picker
          - base_preview
          - base_upload
          - item_delete
          - item_download
          - item_preview
          - item_rename
          - item_share
        object:
          allOf:
          - oneOf:
            - $ref: '#/components/schemas/Folder--Mini'
            - $ref: '#/components/schemas/File--Mini'
          - description: The file or folder resource
    FileVersion--Mini:
      title: File version (Mini)
      type: object
      x-box-resource-id: file_version--mini
      x-box-variant: mini
      description: 'A mini representation of a file version, used when

        nested within another resource.'
      allOf:
      - $ref: '#/components/schemas/FileVersion--Base'
      - properties:
          sha1:
            type: string
            description: The SHA1 hash of this version of the file.
            example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
    User--Mini:
      title: User (Mini)
      type: object
      x-box-resource-id: user--mini
      x-box-variant: mini
      description: 'A mini representation of a user, as can be returned when nested within other

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

        nested under another resource.'
      nullable: true
      allOf:
      - $ref: '#/components/schemas/File--Base'
      - properties:
          sequence_id:
            allOf:
            - type: string
              example: '3'
              nullable: true
              description: 'A numeric identifier that represents the most recent user event

                that has been applied to this item.


                This can be used in combination with the `GET /events`-

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