Box Developer Documentation

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

Register now!

Download File

Download File

To download a file, pass the GET /files/:id/content the ID of the file to get the content for.

cURL
curl -i -L -X GET "https://api.box.com/2.0/files/12345/content" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
TypeScript Gen
const fs = require('fs');

const fileContent = await client.downloads.downloadFile('123456789');
const fileWriteStream = fs.createWriteStream('file.pdf');
fileContent.pipe(fileWriteStream);
Python Gen
client.downloads.download_file(uploaded_file.id)
.NET Gen
await client.Downloads.DownloadFileAsync(fileId: uploadedFile.Id);
Swift Gen (Beta)
let downloadsDirectoryURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!
let destinationURL = downloadsDirectoryURL.appendingPathComponent("file.txt")

let url = try await client.downloads.downloadFile(fileId: file.id, downloadDestinationURL: destinationURL)

if let fileContent = try? String(contentsOf: url, encoding: .utf8) {
    print("The content of the file: \(fileContent)")
}
Java
BoxFile file = new BoxFile(api, "id");
BoxFile.Info info = file.getInfo();

FileOutputStream stream = new FileOutputStream(info.getName());
file.download(stream);
stream.close();
Python
file_id = '11111'
file_content = client.file(file_id).content()
.NET
Stream fileContents = await client.FilesManager.DownloadStreamAsync(id: "11111");
Node
var fs = require('fs');
client.files.getReadStream('12345', null, function(error, stream) {

	if (error) {
		// handle error
	}

	// write the file to disk
	var output = fs.createWriteStream('/path/to/file');
	stream.pipe(output);
});
iOS
let url = FileManager.default.homeDirectoryForCurrentUser

let task: BoxDownloadTask = client.files.download(fileId: "11111", destinationURL: url) { (result: Result<Void, BoxSDKError>) in
    guard case .success = result else {
        print("Error downloading file")
        return
    }

    print("File downloaded successfully")
}

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

Download URL

When not using the SDKs, this API call will return a HTTP 302 Found status code, with a location header containing a link to the download URL, which looks something like this.

https://dl.boxcloud.com/d/1/[long-random-string]/download

By using the -L flag in cURL we are able to automatically follow this redirect.

In our SDKs this will result in the binary data to be downloaded. In the API this will result in a download URL being returned via the location header.

It is possible to get the download URL via the SDKs as well.

Download URL expiry

Although this download URL can be passed to a user's browser to allow them to download the file, the URL does expire and should be requested again for any further downloads.

File not ready

If the file is not ready to be downloaded yet a retry-after header will be returned indicating the time in seconds after which the file will be available for the client to download.

This response can occur when the file was uploaded immediately before the download request.