BObox
Uploads

Upload file

Changed on

Uploads a small file to Box. For file sizes over 50MB we recommend using the Chunk Upload APIs.

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.

post/files/content

Request

  • Base URL
    https://upload.box.com/api/2.0
  • URL
    https://upload.box.com/api/2.0/files/content
  • Auth
    OAuth 2
    Authorization code: https://account.box.com/api/oauth2/authorize
    Token URL: https://api.box.com/oauth2/token

Query parameters

fieldsstring[]

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.

Headers

content-md5string

An optional header containing the SHA1 hash of the file to ensure that the file was not corrupted in transit.

Request body multipart/form-data

filestring binary required

The content of the file to upload to Box.

<Message warning>

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.

</Message>

Example request

{
  "attributes": {
    "name": "Photo.png",
    "parent": {
      "id": "124132"
    },
    "content_created_at": "2012-12-12T10:53:43-08:00",
    "content_modified_at": "2012-12-12T10:53:43-08:00"
  }
}

Response

Returns the new file object in a list.

total_countinteger

The number of files.

Example response

{
  "total_count": 1,
  "entries": [
    {
      "id": "12345",
      "etag": "1",
      "type": "file",
      "sequence_id": "3",
      "name": "Contract.pdf",
      "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
      "file_version": {
        "id": "12345",
        "type": "file_version",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
      },
      "description": "Contract for Q1 renewal",
      "size": 629644,
      "path_collection": {
        "total_count": 1,
        "entries": [
          {
            "id": "12345",
            "etag": "1",
            "type": "folder",
            "sequence_id": "3",
            "name": "Contracts"
          }
        ]
      },
      "created_at": "2012-12-12T10:53:43-08:00",
      "modified_at": "2012-12-12T10:53:43-08:00",
      "trashed_at": "2012-12-12T10:53:43-08:00",
      "purged_at": "2012-12-12T10:53:43-08:00",
      "content_created_at": "2012-12-12T10:53:43-08:00",
      "content_modified_at": "2012-12-12T10:53:43-08:00",
      "created_by": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "modified_by": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "owned_by": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": "https://acme.app.box.com/v/my_url/",
        "vanity_name": "my_url",
        "access": "open",
        "effective_access": "company",
        "effective_permission": "can_download",
        "unshared_at": "2018-04-13T13:53:23-07:00",
        "is_password_enabled": true,
        "permissions": {
          "can_download": true,
          "can_preview": true
        },
        "download_count": 3,
        "preview_count": 3,
        "one_time_passcode": {
          "mode": "allowlist",
          "allowlist": [
            {
              "type": "email",
              "value": "alice@example.com",
              "created_at": "2026-05-19T12:00:00Z",
              "created_by": {
                "id": "11446498",
                "type": "user"
              }
            },
            {
              "type": "domain",
              "value": "example.com",
              "created_at": "2026-05-19T12:00:00Z",
              "created_by": {
                "id": "11446498",
                "type": "user"
              }
            }
          ]
        }
      },
      "parent": {
        "id": "12345",
        "etag": "1",
        "type": "folder",
        "sequence_id": "3",
        "name": "Contracts"
      },
      "item_status": "active",
      "version_number": "1",
      "comment_count": 10,
      "permissions": {
        "can_delete": true,
        "can_download": true,
        "can_invite_collaborator": true,
        "can_rename": true,
        "can_set_share_access": true,
        "can_share": true,
        "can_annotate": true,
        "can_comment": true,
        "can_preview": true,
        "can_upload": true,
        "can_view_annotations_all": true,
        "can_view_annotations_self": true,
        "can_apply_watermark": true
      },
      "tags": [
        "approved"
      ],
      "lock": {
        "id": "11446498",
        "type": "lock",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "expired_at": "2012-12-12T10:53:43-08:00",
        "is_download_prevented": true,
        "app_type": "office_wopiplus"
      },
      "extension": "pdf",
      "is_package": true,
      "expiring_embed_link": {
        "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
        "expires_in": 3600,
        "token_type": "bearer",
        "restricted_to": [
          {
            "scope": "item_download",
            "object": {
              "id": "12345",
              "etag": "1",
              "type": "folder",
              "sequence_id": "3",
              "name": "Contracts"
            }
          }
        ],
        "url": "https://cloud.app.box.com/preview/expiring_embed/..."
      },
      "watermark_info": {
        "is_watermarked": true
      },
      "is_accessible_via_shared_link": true,
      "allowed_invitee_roles": [
        "editor"
      ],
      "is_externally_owned": true,
      "has_collaborations": true,
      "metadata": {
        "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
          }
        }
      },
      "expires_at": "2012-12-12T10:53:43-08:00",
      "representations": {
        "entries": [
          {
            "content": {
              "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
            },
            "info": {
              "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
            },
            "properties": {
              "dimensions": "2048x2048",
              "paged": "true",
              "thumb": "true"
            },
            "representation": "png",
            "status": {
              "state": "success"
            }
          }
        ]
      },
      "classification": {
        "name": "Top Secret",
        "definition": "Content that should not be shared outside the company.",
        "color": "#FF0000"
      },
      "uploader_display_name": "Ellis Wiggins",
      "disposition_at": "2012-12-12T10:53:43-08:00",
      "shared_link_permission_options": [
        "can_preview"
      ],
      "is_associated_with_app_item": true,
      "collections": [
        {
          "id": "11446498",
          "type": "collection",
          "name": "Favorites",
          "collection_type": "favorites"
        }
      ],
      "is_download_available": true,
      "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
      "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
      "allowed_shared_link_access_levels": [
        "open"
      ]
    }
  ]
}

Changes

  • c4d5303fa5c3Revision changes
    • breaking

      the response property //// became nullable for the status

    • breaking

      the response property /// became nullable for the status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added subschema #1 to the /// response property allOf list for the response status

    • info

      added subschema #1 subschema #2 to the //// response property allOf list for the response status

    • info

      added subschema #1 subschema #2 to the /// response property allOf list for the response status

    • info

      added subschema #2 to the //// response property allOf list for the response status

    • info

      added subschema #2 subschema #3 to the ////// response property allOf list for the response status

    • info

      removed subschema #1 subschema #2 from the //// response property allOf list for the response status

    • info

      removed subschema #1 subschema #2 from the /// response property allOf list for the response status

    • info

      removed subschema #1 subschema #3 from the /// response property allOf list for the response status

    • info

      removed subschema #2 subschema #3 from the //// response property allOf list for the response status

    • info

      removed subschema #2 subschema #3 from the ////// response property allOf list for the response status

    • info

      added the required property ////// to the response with the status