Box Developer Documentation
Log in
Latest version

Create zip download

post
https://api.box.com/2.0
/zip_downloads

Creates a request to download multiple files and folders as a single zip archive file. This API does not return the archive but instead performs all the checks to ensure that the user has access to all the items, and then returns a download_url and a status_url that can be used to download the archive.

The limit for an archive is either the Account's upload limit or 10,000 files, whichever is met first.

Note: Downloading a large file can be affected by various factors such as distance, network latency, bandwidth, and congestion, as well as packet loss ratio and current server load. For these reasons we recommend that a maximum ZIP archive total size does not exceed 25GB.

Related Guides

Request

bearer [ACCESS_TOKEN]
application/json

Request Body

stringin bodyoptional
"January Financials"

The optional name of the zip archive. This name will be appended by the .zip file extension, for example January Financials.zip.

object arrayin bodyrequired

A list of items to add to the zip archive. These can be folders or files.

stringin bodyrequired
"12345"

The identifier of the item to add to the archive. When this item is a folder then this can not be the root folder with ID 0.

stringin bodyrequired
"file"

The type of the item to add to the archive.

Value is one of file,folder

Response

application/jsonZip download

If the zip archive is ready to be downloaded, the API will return a response that will include a download_url, a status_url, as well as any conflicts that might have occurred when creating the request.

application/jsonClient error

Returns an error if some of the parameters are missing or not valid.

In most cases, this error might happen because the JSON request body is not valid JSON, any of the items has an incorrect or missing ID, any of the items is not a file or folder, or the root folder with ID 0 has been added to the list of folders to add to the archive.

The following is a list of common error codes for this response.

  • bad_request - the request body is missing, invalid, or both the list of files and folders are empty. Additionally, it this error might be returned when attempting to add the root folder with ID 0 to an archive.
  • zip_download_file_count_exceeded_limit - the requested files and folders would result in an archive with more than 10,000 files. The request will have to be split into multiple requests to reduce the number of files per archive.
  • zip_download_pre_compressed_bytes_exceeded_limit - the requested files and folders would result in an archive with more than the allowed download limit. The request will have to be split into multiple requests to reduce the size of the archive.
application/jsonClient error

Returned when the access token provided in the Authorization header is not recognized or not provided.

application/jsonClient error

Returned when an authorization header is provided but the user does not have access to the items.

application/jsonClient error

An unexpected client error.

post
Create zip download
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
curl -i -X POST "https://api.box.com/2.0/zip_downloads" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
       "download_file_name": "January Financials",
       "items": [
         {
           "type": "file",
           "id": "12345"
         },
         {
           "type": "file",
           "id": "34325"
         },
         {
           "type": "folder",
           "id": "45678"
         }
       ]
     }'
TypeScript Gen
await client.zipDownloads.createZipDownload({
  items: [
    {
      id: file1.id,
      type: 'file' as ZipDownloadRequestItemsTypeField,
    } satisfies ZipDownloadRequestItemsField,
    {
      id: file2.id,
      type: 'file' as ZipDownloadRequestItemsTypeField,
    } satisfies ZipDownloadRequestItemsField,
    {
      id: folder1.id,
      type: 'folder' as ZipDownloadRequestItemsTypeField,
    } satisfies ZipDownloadRequestItemsField,
  ],
  downloadFileName: 'zip',
} satisfies ZipDownloadRequest);
Python Gen
client.zip_downloads.create_zip_download(
    [
        CreateZipDownloadItems(id=file_1.id, type=DownloadZipItemsTypeField.FILE.value),
        CreateZipDownloadItems(id=file_2.id, type=DownloadZipItemsTypeField.FILE.value),
        CreateZipDownloadItems(
            id=folder_1.id, type=DownloadZipItemsTypeField.FOLDER.value
        ),
    ],
    download_file_name="zip",
)
.NET Gen
await client.ZipDownloads.CreateZipDownloadAsync(requestBody: new ZipDownloadRequest(items: Array.AsReadOnly(new [] {new ZipDownloadRequestItemsField(id: file1.Id, type: ZipDownloadRequestItemsTypeField.File),new ZipDownloadRequestItemsField(id: file2.Id, type: ZipDownloadRequestItemsTypeField.File),new ZipDownloadRequestItemsField(id: folder1.Id, type: ZipDownloadRequestItemsTypeField.Folder)})) { DownloadFileName = "zip" });
Java
ArrayList<BoxZipItem> items = new ArrayList<BoxZipItem>();
BoxZipItem file = new BoxZipItem("file", "12345");
BoxZipItem folder = new BoxZipItem("folder", "156472");
items.add(file);
items.add(folder);
BoxZip zip = new BoxZip(api);
BoxZipInfo zipInfo = zip.create("Awesome Zip File", items);
Node
var name = 'test',
items = [
	{
		type: 'file',
		id: '466239504569'
	},
	{
		type: 'folder',
		id: '466239504580'
	}
];
client.files.createZip(name, items)
	.then(zip => {
		/* zip -> {
				"download_url": "https://api.box.com/2.0/zip_downloads/124hfiowk3fa8kmrwh/content",
				"status_url": "https://api.box.com/2.0/zip_downloads/124hfiowk3fa8kmrwh/status",
				"expires_at": "2018-04-25T11:00:18-07:00",
				"name_conflicts": [
					[
						{
							"id": "100",
							"type": "file",
							"original_name": "salary.pdf",
							"download_name": "aqc823.pdf"
						},
						{
							"id": "200",
							"type": "file",
							"original_name": "salary.pdf",
							"download_name": "aci23s.pdf"
						}
					],
					[
						{
							"id": "1000",
							"type": "folder",
							"original_name": "employees",
							"download_name": "3d366a_employees"
						},
						{
							"id": "2000",
							"type": "folder",
							"original_name": "employees",
							"download_name": "3aa6a7_employees"
						}
					]
				]
			}
		*/
	});

Response Example

{
  "download_url": "https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content",
  "status_url": "https://api.box.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status",
  "expires_at": "2020-07-22T11:26:08Z",
  "name_conflicts": [
    [
      {
        "id": "12345",
        "type": "file",
        "original_name": "Report.pdf",
        "download_name": "3aa6a7.pdf"
      },
      {
        "id": "34325",
        "type": "file",
        "original_name": "Report.pdf",
        "download_name": "5d53f2.pdf"
      }
    ]
  ]
}