Upload a file

post
https://upload.box.com/api/2.0
/files/content

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.

Request

multipart/form-data

Query Parameters

string arrayin queryoptional
id,type,name

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.

Request Body

objectin body

The additional attributes of the file being uploaded. Mainly the name and the parent folder. These attributes are part of the multi part request body and are in JSON format.

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.

string / date-timein bodyoptional
2012-12-12T10:53:43-08:00

Defines the time the file was originally created at.

If not set, the upload time will be used.

string / date-timein bodyoptional
2012-12-12T10:53:43-08:00

Defines the time the file was last modified at.

If not set, the upload time will be used.

stringin bodyrequired
Photo.png

The name of the file

objectin body

The parent folder to upload the file to

stringin bodyrequired
124132

The id of the parent folder. Use 0 for the user's root folder.

string / binaryin bodyrequired

The content of the file to upload to Box.

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.

Request Headers

stringin headeroptional
134b65991ed521fcfe4724b7d814ab8ded5185dc

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

Response

application/jsonFiles

Returns the new file object in a list.

application/jsonClient Error

Returns an error if the file already exists, or the account has run out of disk space.

You can now try out some of our APIs live, right here in the documentation.
Log In

Request Example

cURL
curl -X POST https://upload.box.com/api/2.0/files/content \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: multipart/form-data" \
     -F attributes='{"name":"Photo.jpg", "parent":{"id":"11446498"}}' \
     -F file=@<FILE_NAME>
.NET
using (FileStream fileStream = new FileStream(filePath, FileMode.Open))
{
    BoxFileRequest requestParams = new BoxFileRequest()
    {
        Name = uploadFileName,
        Parent = new BoxRequestEntity() { Id = "0" }
    };

    BoxFile file = await client.FilesManager.UploadAsync(requestParams, fileStream);
}
Java
BoxFolder rootFolder = BoxFolder.getRootFolder(api);
FileInputStream stream = new FileInputStream("My File.txt");
BoxFile.Info newFileInfo = rootFolder.uploadFile(stream, "My File.txt");
stream.close();
Python
folder_id = '22222'
new_file = client.folder(folder_id).upload('/home/me/document.pdf')
print('File "{0}" uploaded to Box with file ID {1}'.format(new_file.name, new_file.id))
Node
var fs = require('fs');
var stream = fs.createReadStream('/path/to/My File.pdf');
var folderID = '0'
client.files.uploadFile(folderID, 'My File.pdf', stream)
	.then(file => {
		/* file -> {
			total_count: 1,
			entries: 
			[ { type: 'file',
				id: '11111',
				file_version: 
					{ type: 'file_version',
					id: '22222',
					sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33' },
				sequence_id: '0',
				etag: '0',
				sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33',
				name: 'My File.pdf',
				description: '',
				size: 68431,
				path_collection: 
					{ total_count: 1,
					entries: 
					[ { type: 'folder',
						id: '0',
						sequence_id: null,
						etag: null,
						name: 'All Files' } ] },
				created_at: '2017-05-16T15:18:02-07:00',
				modified_at: '2017-05-16T15:18:02-07:00',
				trashed_at: null,
				purged_at: null,
				content_created_at: '2017-05-16T15:18:02-07:00',
				content_modified_at: '2017-05-16T15:18:02-07:00',
				created_by: 
					{ type: 'user',
					id: '33333',
					name: 'Test User',
					login: 'test@example.com' },
				modified_by: 
					{ type: 'user',
					id: '33333',
					name: 'Test User',
					login: 'test@example.com' },
				owned_by: 
					{ type: 'user',
					id: '33333',
					name: 'Test User',
					login: 'test@example.com' },
				shared_link: null,
				parent: 
					{ type: 'folder',
					id: '0',
					sequence_id: null,
					etag: null,
					name: 'All Files' }
				item_status: 'active' } ] }
		*/
	});

Response Example

{
  "total_count": 1,
  "entries": [
    {
      "id": 12345,
      "etag": 1,
      "type": "file",
      "sequence_id": 3,
      "name": "Contract.pdf",
      "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
      "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/",
        "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
      },
      "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
      },
      "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
      },
      "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": "file",
              "sequence_id": 3,
              "name": "Contract.pdf"
            }
          }
        ],
        "url": "https://cloud.app.box.com/preview/expiring_embed/..."
      },
      "watermark_info": {
        "is_watermarked": true
      },
      "allowed_invitee_roles": [
        "open"
      ],
      "is_externally_owned": true,
      "has_collaborations": true,
      "metadata": {
        "global": {
          "marketingCollateral": {
            "$canEdit": true,
            "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
            "$parent": "folder_59449484661",
            "$scope": "enterprise_27335",
            "$template": "blueprintTemplate",
            "$type": "blueprintTemplate-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"
            }
          }
        ]
      }
    }
  ]
}