Box Uploads (Chunked) API

openapi: 3.2.0
info:
  title: Box Platform Uploads (Chunked) API
  description: '[Box Platform](https://box.dev) provides functionality to provide access to content stored within [Box](https://box.com). It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies.'
  termsOfService: https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9
  contact:
    name: Box, Inc
    url: https://box.dev
    email: devrel@box.com
  license:
    name: Apache-2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  version: 2.0.0
  x-box-commit-hash: '5819125043'
servers:
- url: https://api.box.com/2.0
  description: Box Platform API server
security:
- OAuth2Security: []
tags:
- name: Uploads (Chunked)
  description: 'The chunked upload endpoints support files from

    20MB in size and allow an application

    to upload the file in parts,

    allowing for more control to catch any errors

    and retry parts individually.'
  x-box-tag: chunked_uploads
paths:
  /files/upload_sessions:
    post:
      operationId: post_files_upload_sessions
      summary: Box Create upload session
      tags:
      - Uploads (Chunked)
      x-box-tag: chunked_uploads
      description: Creates an upload session for a new file.
      servers:
      - url: https://upload.box.com/api/2.0
        description: Server for file uploads
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - folder_id
              - file_size
              - file_name
              properties:
                folder_id:
                  description: The ID of the folder to upload the new file to.
                  type: string
                  example: '0'
                file_size:
                  description: The total number of bytes of the file to be uploaded
                  example: 104857600
                  type: integer
                  format: int64
                file_name:
                  description: The name of new file
                  example: Project.mov
                  type: string
      responses:
        '201':
          description: Returns a new upload session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSession'
        '400':
          description: "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `missing_destination`: No `folder_id` was provided\n* `invalid_folder_id`: `folder_id` is not valid\n* `item_name_invalid`: `file_name` is not valid\n* `missing_file_size`: `file_size` was not provided\n* `invalid_file_size`: `file_size` was not a valid number\n* `file_size_too_small`: `file_size` is below minimum file size for\n  uploads via this API\n* `missing_file_name`: `file_name` was not provided"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: 'Returns an error if the operation is not allowed for some reason.


            * `storage_limit_exceeded`: Account storage limit reached'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: "Returns an error if the parent folder could not be found, or\nthe authenticated user does not have access to it.\n\n* `invalid_parameter`: The `folder_id` value represents a\n  folder that the user does not have access to, or does not\n  exist."
          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'
  /files/{file_id}/upload_sessions:
    post:
      operationId: post_files_id_upload_sessions
      summary: Box Create upload session for existing file
      tags:
      - Uploads (Chunked)
      x-box-tag: chunked_uploads
      description: Creates an upload session for an existing file.
      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
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - file_size
              properties:
                file_size:
                  description: The total number of bytes of the file to be uploaded
                  example: 104857600
                  type: integer
                  format: int64
                file_name:
                  description: The optional new name of new file
                  example: Project.mov
                  type: string
      responses:
        '201':
          description: Returns a new upload session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSession'
        '409':
          description: 'Returns an error if the file already exists,

            or if 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'
  /files/upload_sessions/{upload_session_id}:
    get:
      operationId: get_files_upload_sessions_id
      summary: Box Get upload session
      tags:
      - Uploads (Chunked)
      description: Return information about an upload session.
      x-box-tag: chunked_uploads
      servers:
      - url: https://upload.box.com/api/2.0
        description: Server for file uploads
      parameters:
      - name: upload_session_id
        description: The ID of the upload session.
        example: D5E3F7A
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns an upload session object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSession'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    put:
      operationId: put_files_upload_sessions_id
      summary: Box Upload part of file
      tags:
      - Uploads (Chunked)
      x-box-tag: chunked_uploads
      description: Updates a chunk of an upload session for a file.
      servers:
      - url: https://upload.box.com/api/2.0
        description: Server for file uploads
      parameters:
      - name: upload_session_id
        description: The ID of the upload session.
        example: D5E3F7A
        in: path
        required: true
        schema:
          type: string
      - name: digest
        description: 'The [RFC3230][1] message digest of the chunk uploaded.


          Only SHA1 is supported. The SHA1 digest must be base64

          encoded. The format of this header is as

          `sha=BASE64_ENCODED_DIGEST`.


          To get the value for the `SHA` digest, use the

          openSSL command to encode the file part:

          `openssl sha1 -binary <FILE_PART_NAME> | base64`


          [1]: https://tools.ietf.org/html/rfc3230'
        example: sha=fpRyg5eVQletdZqEKaFlqwBXJzM=
        in: header
        required: true
        schema:
          type: string
      - name: content-range
        description: "The byte range of the chunk.\n\nMust not overlap with the range of a part already\nuploaded this session. Each part’s size must be\nexactly equal in size to the part size specified\nin the upload session that you created.\nOne exception is the last part of the file, as this can be smaller.\n\nWhen providing the value for `content-range`, remember that:\n\n* The lower bound of each part's byte range\n  must be a multiple of the part size.\n* The higher bound must be a multiple of the part size - 1."
        example: bytes 8388608-16777215/445856194
        in: header
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
              description: The binary content of the file
      responses:
        '200':
          description: Chunk has been uploaded successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadedPart'
        '409':
          description: 'Returns an error if the chunk conflicts with another

            chunk previously uploaded.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '412':
          description: Returns an error if a precondition was not met.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '416':
          description: 'Returns an error if the content range does not match a specified range

            for the session.'
          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_upload_sessions_id
      summary: Box Remove upload session
      tags:
      - Uploads (Chunked)
      description: 'Abort an upload session and discard all data uploaded.


        This cannot be reversed.'
      servers:
      - url: https://upload.box.com/api/2.0
        description: Server for file uploads
      x-box-tag: chunked_uploads
      parameters:
      - name: upload_session_id
        description: The ID of the upload session.
        example: D5E3F7A
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 'A blank response is returned if the session was

            successfully aborted.'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /files/upload_sessions/{upload_session_id}/parts:
    get:
      operationId: get_files_upload_sessions_id_parts
      summary: Box List parts
      tags:
      - Uploads (Chunked)
      x-box-tag: chunked_uploads
      servers:
      - url: https://upload.box.com/api/2.0
        description: Server for file uploads
      description: 'Return a list of the chunks uploaded to the upload

        session so far.'
      parameters:
      - name: upload_session_id
        description: The ID of the upload session.
        example: D5E3F7A
        in: path
        required: true
        schema:
          type: string
      - name: offset
        description: 'The offset of the item at which to begin the response.


          Queries with offset parameter value

          exceeding 10000 will be rejected

          with a 400 response.'
        in: query
        required: false
        example: 1000
        schema:
          type: integer
          format: int64
          default: 0
      - 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 a list of parts that have been uploaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadParts'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /files/upload_sessions/{upload_session_id}/commit:
    post:
      operationId: post_files_upload_sessions_id_commit
      summary: Box Commit upload session
      tags:
      - Uploads (Chunked)
      x-box-tag: chunked_uploads
      servers:
      - url: https://upload.box.com/api/2.0
        description: Server for file uploads
      description: 'Close an upload session and create a file from the

        uploaded chunks.'
      parameters:
      - name: upload_session_id
        description: The ID of the upload session.
        example: D5E3F7A
        in: path
        required: true
        schema:
          type: string
      - name: digest
        description: 'The [RFC3230][1] message digest of the whole file.


          Only SHA1 is supported. The SHA1 digest must be Base64

          encoded. The format of this header is as

          `sha=BASE64_ENCODED_DIGEST`.


          [1]: https://tools.ietf.org/html/rfc3230'
        in: header
        example: sha=fpRyg5eVQletdZqEKaFlqwBXJzM=
        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: if-none-match
        description: 'Ensures an item is only returned if it has changed.


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

          into this header and the endpoint will fail

          with a `304 Not Modified` if the item has not

          changed since.'
        in: header
        required: false
        example: '1'
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - parts
              properties:
                parts:
                  type: array
                  description: The list details for the uploaded parts
                  items:
                    $ref: '#/components/schemas/UploadPart'
      responses:
        '201':
          description: Returns the file object in a list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Files'
        '202':
          description: 'Returns when all chunks have been uploaded but not yet processed.


            Inspect the upload session to get more information about the

            progress of processing the chunks, then retry committing the file

            when all chunks have processed.'
          headers:
            Retry-After:
              description: 'Indicates the number of seconds the client should wait before

                attempting their commit request again.'
              schema:
                type: integer
        '409':
          description: 'Returns an error if there is already a file with the same name

            in the target folder.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '412':
          description: Returns an error if the `If-Match` or `If-None-Match` conditions fail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    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'
    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
        status:
          description: The HTTP status of the response.
          example: 400
          type: integer
          format: int32
        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
        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
          - 'null'
          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
        request_id:
          description: 'A unique identifier for this response, which can be used

            when contacting Box support.'
          type: string
          example: abcdef123456
    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
    FileVersion--Base:
      title: File version (Base)
      type: object
      x-box-resource-id: file_version--base
      x-box-sanitized: true
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'The bare basic representation of a file version, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          description: The unique identifier that represent a file version.
          example: '12345'
        type:
          type: string
          description: '`file_version`'
          example: file_version
          enum:
          - file_version
    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
          enum:
          - user
    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
          login:
            type: string
            format: email
            description: The primary email address of this user
            example: ceo@example.com
    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
            description: The optional description of this file
            maxLength: 256
            example: Contract for Q1 renewal
          size:
            type: integer
            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
                entries:
                  type: array
                  description: The parent folders for this item
                  items:
                    $ref: '#/components/schemas/Folder--Mini'
            - description: 'The tree of folders that this file is contained in,

                starting at the root.'
            - {}
          created_at:
            type: string
            format: date-time
            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
            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
            - 'null'
            format: date-time
            description: The time at which this file was put in the trash.
            example: '2012-12-12T10:53:43-08:00'
          purged_at:
            type:
            - string
            - 'null'
            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'
          content_created_at:
            type:
            - string
            - 'null'
            format: date-time
            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
            - 'null'
            format: date-time
            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
            - {}
          owned_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who owns this file
            - {}
          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
                download_url:
                  type:
                  - string
                  - 'null'
                  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
                vanity_url:
                  type:
                  - string
                  - 'null'
                  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/
                vanity_name:
                  type:
                  - string
                  - 'null'
                  description: The custom name of a shared link, as used in the `vanity_url` field.
                  example: my_url
                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
                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
                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
                unshared_at:
                  type:
                  - string
                  - 'null'
                  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'
                is_password_enabled:
                  type: boolean
                  description: Defines if the shared link requires a password to access the item.
                  example: true
                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
                      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
                      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
                      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.
                preview_count:
                  type: integer
                  example: 3
                  description: The number of times this item has been previewed.
            - description: 'The shared link for this file. This will be

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

                file.'
            - {}
          parent:
            allOf:
            - $ref: '#/components/schemas/Folder--Mini'
            - description: The folder that this file is located within.
          item_status:
            type: string
            description: 'Defines if this i

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