Box

Box Uploads API

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.

Documentation GitHub OpenAPI

Operations 2

POST /files/{file_id}/content Box Upload file version #

POST /files/content Box Upload file #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/box-uploads-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Box Platform Uploads 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
  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:
    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--Full:
      title: File (Full)
      type: object
      x-box-resource-id: file--full
      x-box-variant: full
      description: 'A full representation of a file, as can be returned from any

        file API endpoints by default'
      allOf:
      - $ref: '#/components/schemas/File'
      - properties:
          version_number:
            type: string
            example: '1'
            description: The version number of this file
          comment_count:
            type: integer
            example: 10
            description: The number of comments on this file
          permissions:
            allOf:
            - type: object
              description: The permissions that the authenticated user has for a file.
              required:
              - can_annotate
              - can_comment
              - can_preview
              - can_upload
              - can_view_annotations_all
              - can_view_annotations_self
              allOf:
              - type: object
                description: The permissions that the authenticated user has for an item.
                required:
                - can_delete
                - can_download
                - can_invite_collaborator
                - can_rename
                - can_set_share_access
                - can_share
                properties:
                  can_delete:
                    type: boolean
                    description: Specifies if the current user can delete this item.
                    example: true
                  can_download:
                    type: boolean
                    description: Specifies if the current user can download this item.
                    example: true
                  can_invite_collaborator:
                    type: boolean
                    description: 'Specifies if the current user can invite new

                      users to collaborate on this item, and if the user can

                      update the role of a user already collaborated on this

                      item.'
                    example: true
                  can_rename:
                    type: boolean
                    description: Specifies if the user can rename this item.
                    example: true
                  can_set_share_access:
                    type: boolean
                    description: 'Specifies if the user can change the access level of an

                      existing shared link on this item.'
                    example: true
                  can_share:
                    type: boolean
                    description: Specifies if the user can create a shared link for this item.
                    example: true
              - properties:
                  can_annotate:
                    type: boolean
                    description: Specifies if the user can place annotations on this file.
                    example: true
                  can_comment:
                    type: boolean
                    description: Specifies if the user can place comments on this file.
                    example: true
                  can_preview:
                    type: boolean
                    description: Specifies if the user can preview this file.
                    example: true
                  can_upload:
                    type: boolean
                    description: Specifies if the user can upload a new version of this file.
                    example: true
                  can_view_annotations_all:
                    type: boolean
                    description: Specifies if the user view all annotations placed on this file
                    example: true
                  can_view_annotations_self:
                    type: boolean
                    description: 'Specifies if the user view annotations placed by themselves

                      on this file'
                    example: true
            - description: 'Describes the permissions that the current user has

                for this file.'
            - {}
          tags:
            allOf:
            - type: array
              example:
              - approved
              items:
                type: string
              minItems: 1
              maxItems: 100
              description: 'The tags for this item. These tags are shown in

                the Box web app and mobile apps next to an item.


                To add or remove a tag, retrieve the item''s current tags,

                modify them, and then update this field.


                There is a limit of 100 tags per item, and 10,000

                unique tags per enterprise.'
            - {}
          lock:
            allOf:
            - title: Lock
              type: object
              description: 'The lock held on a file. A lock prevents a file from being moved,

                renamed, or otherwise changed by anyone else than the user who created the

                lock.'
              properties:
                id:
                  type: string
                  description: The unique identifier for this lock
                  example: '11446498'
                type:
                  type: string
                  description: '`lock`'
                  example: lock
                  enum:
                  - lock
                created_by:
                  allOf:
                  - $ref: '#/components/schemas/User--Mini'
                  - description: The user who created the lock.
                created_at:
                  type: string
                  format: date-time
                  example: '2012-12-12T10:53:43-08:00'
                  description: The time this lock was created at.
                expired_at:
                  type: string
                  format: date-time
                  example: '2012-12-12T10:53:43-08:00'
                  description: The time this lock is to expire at, which might be in the past.
                is_download_prevented:
                  type: boolean
                  example: true
                  description: Whether or not the file can be downloaded while locked.
                app_type:
                  type:
                  - string
                  - 'null'
                  description: 'If the lock is managed by an application rather than a user, this

                    field identifies the type of the application that holds the lock.

                    This is an open enum and may be extended with additional values in

                    the future.'
                  enum:
                  - gsuite
                  - office_wopi
                  - office_wopiplus
                  - other
                  example: office_wopiplus
            - description: 'The lock held on this file. If there is no lock, this can either

                be `null` or have a timestamp in the past.'
          extension:
            type: string
            example: pdf
            description: 'Indicates the (optional) file extension for this file. By default,

              this is set to an empty string.'
          is_package:
            type: boolean
            example: true
            description: 'Indicates if the file is a package. Packages are commonly used

              by Mac Applications and can include iWork files.'
          expiring_embed_link:
            allOf:
            - title: Expiring embed link
              type: object
              description: An expiring Box Embed Link.
              allOf:
              - type: object
                description: The basics of an access token
                properties:
                  access_token:
                    type: string
                    format: token
                    example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
                    description: The requested access token.
                  expires_in:
                    type: integer
                    format: int64
                    example: 3600
                    description: The time in seconds by which this token will expire.
                  token_type:
                    type: string
                    enum:
                    - bearer
                    example: bearer
                    description: The type of access token returned.
                  restricted_to:
                    type: array
                    description: 'The permissions that this access token permits,

                      providing a list of resources (files, folders, etc)

                      and the scopes permitted for each of those resources.'
                    items:
                      $ref: '#/components/schemas/FileOrFolderScope'
              - properties:
                  url:
                    type: string
                    format: url
                    example: https://cloud.app.box.com/preview/expiring_embed/...
                    description: 'The actual expiring embed URL for this file, constructed

                      from the file ID and access tokens specified in this object.'
            - description: 'Requesting this field creates an expiring Box Embed URL for an

                embedded preview session in an `iframe`.


                This URL will expire after 60 seconds and the session will

                expire after 60 minutes.


                Not all file types are supported for these embed URLs. Box Embed

                is not optimized for mobile browsers and should not be used in web

                experiences designed for mobile devices. Many UI elements, like

                the **download** and **print** options might not show in mobile

                browsers.'
          watermark_info:
            allOf:
            - type: object
              description: Details about the watermark applied to this item
              properties:
                is_watermarked:
                  type: boolean
                  description: Specifies if this item has a watermark applied.
                  example: true
            - description: Details about the watermark applied to this file
          is_accessible_via_shared_link:
            type: boolean
            description: 'Specifies if the file can be accessed

              via the direct shared link or a shared link

              to a parent folder.'
            example: true
            enum:
            - true
            - false
          allowed_invitee_roles:
            type: array
            example:
            - editor
            description: 'A list of the types of roles that user can be invited at

              when sharing this file.'
            items:
              type: string
              enum:
              - editor
              - viewer
              - previewer
              - uploader
              - previewer uploader
              - viewer uploader
              - co-owner
          is_externally_owned:
            type: boolean
            example: true
            description: 'Specifies if this file is owned by a user outside of the

              authenticated enterprise.'
          has_collaborations:
            type: boolean
            example: true
            description: Specifies if this file has any other collaborators.
          metadata:
            allOf:
            - title: Item metadata instances
              type: object
              description: 'A list of metadata instances, nested within key-value pairs of their `scope`

                and `templateKey`.


                To access the metadata for a file or folder, first use the

                metadata endpoints to determine the metadata templates available to your

                enterprise.


                Then use the `GET /files/:id` or `GET /folder/:id`

                endpoint with the `fields` query parameter to get

                the metadata by ID.


                To request a metadata instance for a particular `scope` and `templateKey`

                use the following format for the `fields` parameter:

                `metadata.<scope>.<templateKey>`


                For example, `?fields=metadata.enterprise_27335.marketingCollateral`.'
              example:
                enterprise_27335:
                  marketingCollateral:
                    $canEdit: true
                    $id: 01234500-12f1-1234-aa12-b1d234cb567e
                    $parent: folder_59449484661
                    $scope: enterprise_27335
                    $template: marketingCollateral
                    $type: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
                    $typeVersion: 2
                    $version: 1
              additionalProperties:
                type: object
                description: 'A list of metadata instances, nested within key-value pairs of their `scope`

                  and `templateKey`.'
                example:
                  marketingCollateral:
                    $canEdit: true
                    $id: 01234500-12f1-1234-aa12-b1d234cb567e
                    $parent: folder_59449484661
                    $scope: enterprise_27335
                    $template: marketingCollateral
                    $type: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
                    $typeVersion: 2
                    $version: 1
                additionalProperties:
                  $ref: '#/components/schemas/Metadata'
            - description: 'An object containing the metadata instances that have been

                attached to this file.


                Each metadata instance is uniquely identified by its `scope` and

                `templateKey`. There can only be one instance of any metadata

                template attached to each file. Each metadata instance is nested

                within an object with the `templateKey` as the key, which again

                itself is nested in an object with the `scope` as the key.'
          expires_at:
            type:
            - string
            - 'null'
            format: date-time
            description: When the file will automatically be deleted
            example: '2012-12-12T10:53:43-08:00'
          representations:
            allOf:
            - title: Representations
              description: A list of file representations
              type: object
              properties:
                entries:
                  type: array
                  description: A list of files
                  items:
                    type: object
                    description: A file representation
                    properties:
                      content:
                        type: object
                        description: 'An object containing the URL that can be used to actually fetch

                          the representation.'
                        properties:
                          url_template:
                            type: string
                            example: https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567
                            description: "The download URL that can be used to fetch the representation.\nMake sure to make an authenticated API call to this endpoint.\n\nThis URL is a template and will require the `{+asset_path}` to\nbe replaced by a path. In general, for unpaged representations\nit can be replaced by an empty string.\n\nFor paged representations, replace the `{+asset_path}` with the\npage to request plus the extension for the file, for example\n`1.pdf`.\n\nWhen requesting the download URL the following additional\nquery params can be passed along.\n\n* `set_content_disposition_type` - Sets the\n`Content-Disposition` header in the API response with the\nspecified disposition type of either `inline` or `attachment`.\nIf not supplied, the `Content-Disposition` header is not\nincluded in the response.\n\n* `set_content_disposition_filename` - Allows the application to\n  define the representation's file name used in the\n  `Content-Disposition` header.  If not defined, the filename\n  is derived from the source file name in Box combined with the\n  extension of the representation."
                      info:
                        type: object
                        description: 'An object containing the URL that can be used to fetch more info

                          on this representation.'
                        properties:
                          url:
                            type: string
                            example: https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048
                            description: 'The API URL that can be used to get more info on this file

                              representation. Make sure to make an authenticated API call

                              to this endpoint.'
                      properties:
                        type: object
                        description: An object containing the size and type of this presentation.
                        properties:
                          dimensions:
                            type: string
                            format: <width>x<height>
                            example: 2048x2048
                            description: The width by height size of this representation in pixels.
                          paged:
                            type: boolean
                            example: true
                            description: 'Indicates if the representation is build up out of multiple

                              pages.'
                          thumb:
                            type: boolean
                            example: true
                            description: 'Indicates if the representation can be used as a thumbnail of

                              the file.'
                      representation:
                        type: string
                        example: png
                        description: Indicates the file type of the returned representation.
                      status:
                        type: object
                        description: An object containing the status of this representation.
                        properties:
                          state:
                            type: string
                            example: success
                            enum:
                            - success
                            - viewable
                            - pending
                            - none
                            description: "The status of the representation.\n\n* `success` defines the representation as ready to be viewed.\n* `viewable` defines a video to be ready for viewing.\n* `pending` defines the representation as to be generated. Retry\n  this endpoint to re-check the status.\n* `none` defines that the representation will be created when\n  requested. Request the URL defined in the `info` object to\n  trigger this generation."
            - description: 'A list of representations for a file that can be used to

                display a placeholder of the file in your application. By default

                this returns all representations and we recommend using the

                `x-rep-hints` header to further customize the desired

                representations.'
          classification:
            allOf:
            - type: object
              description: The classification applied to an item
              properties:
                name:
                  type: string
                  example: Top Secret
                  description: The name of the classification
                definition:
                  type: string
                  example: Content that should not be shared outside the company.
                  description: An explanation of the meaning of this classification.
                color:
                  type: string
                  example: '#FF0000'
                  description: 'The color that is used to display the

                    classification label in a user-interface. Colors are defined by the a

# --- 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