Box Developer Documentation

Join BoxWorks 2024 to discover what's possible with content and AI!

Register now!

Upload New File

Upload New File

To upload a file to Box via direct upload, make an API call to the POST /files/content API with the content of the file, the desired file name, and the folder ID.

cURL
curl -i -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":"Contract.pdf", "parent":{"id":"11446498"}}' \
     -F file=@<FILE_NAME>
TypeScript Gen
const fs = require('fs');

const attrs = { name: 'filename.txt', parent: { id: '0' } };
const body = {
  attributes: attrs,
  file: fs.createReadStream('filename.txt'),
};
const files = await client.uploads.uploadFile(body);
const file = files.entries[0];
console.log(`File uploaded with id ${file.id}, name ${file.name}`);
Python Gen
parent_client.uploads.upload_file(
    UploadFileAttributes(
        name=get_uuid(), parent=UploadFileAttributesParentField(id="0")
    ),
    generate_byte_stream(1024 * 1024),
)
.NET Gen
await parentClient.Uploads.UploadFileAsync(requestBody: new UploadFileRequestBody(attributes: new UploadFileRequestBodyAttributesField(name: Utils.GetUUID(), parent: new UploadFileRequestBodyAttributesParentField(id: "0")), file: Utils.GenerateByteStream(size: 1024 * 1024)));
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(f'File "{new_file.name}" uploaded to Box with file ID {new_file.id}')
.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);
}
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' } ] }
		*/
	});
iOS
let data = "test content".data(using: .utf8)

let task: BoxUploadTask = client.files.upload(data: data, name: "Test File.txt", parentId: "0") { (result: Result<File, BoxSDKError>) in
    guard case let .success(file) = result else {
        print("Error uploading file")
        return
    }

    print("File \(file.name) was uploaded at \(file.createdAt) into \"\(file.parent.name)\"")
}

// To cancel upload
if someConditionIsSatisfied {
    task.cancel()
}

Preflight check

To prevent wasting time and bandwidth uploading a file that is going to be rejected it is recommended to perform a pre-flight check before uploading the file.

Request Format

The request body of this API uses a content type of multipart/form-data. This is used to transmit two parts, namely the file attributes and the file's actual content.

The first part is called attributes and contains a JSON object with information about the file, including the name of the file and the id of the parent folder.

The following is an example a test.txt being uploaded to the root folder of the user.

POST /api/2.0/files/content HTTP/1.1
Host: upload.box.com
Authorization: Bearer [ACCESS_TOKEN]
content-length: 343
content-type: multipart/form-data; boundary=------------------------9fd09388d840fef1

--------------------------9fd09388d840fef1
content-disposition: form-data; name="attributes"

{"name":"test.txt", "parent":{"id":"0"}}
--------------------------9fd09388d840fef1
content-disposition: form-data; name="file"; filename="test.txt"
content-type: text/plain

Test file text.

--------------------------9fd09388d840fef1--

The attributes JSON part of the multi-part body must come before the file part of the multipart form data. When out of order, the API will return a HTTP 400 status code with an error code of metadata_after_file_contents.

Options

To learn more about all the parameters available when uploading files, head over to the reference documentation for this API call. These parameters include a content-md5 that can be set to ensure a file is not corrupted in transit, and the ability to explicitly specify the file creation time at a different time than the upload time.

Restrictions

Direct uploads are limited to a maximum file size of 50MB. For larger files, please use the chunked upload APIs.

Upload limits are dictated by the type of account of the authenticated user. More information can be found in our community article on this topic.