Skip to main content
POST
/
zip_downloads
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"
         }
       ]
     }'
{
  "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"
      }
    ]
  ]
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

A request to create a zip archive to download.

​
items
object[]
required

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

​
download_file_name
string

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

Example:

"January Financials"

Response

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.

Represents a successful request to create a zip archive of a list of files and folders.

​
download_url
string

The URL that can be used to download the zip archive. A Get request to this URL will start streaming the items requested. By default, this URL is only valid for a few seconds, until the expires_at time, unless a download is started after which it is valid for the duration of the download.

It is important to note that the domain and path of this URL might change between API calls, and therefore it's important to use this URL as-is.

Example:

"https://dl.boxcloud.com/2.0/zip_downloads/Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd/content"

​
status_url
string

The URL that can be used to get the status of the zip archive being downloaded. A Get request to this URL will return the number of files in the archive as well as the number of items already downloaded or skipped. By default, this URL is only valid for a few seconds, until the expires_at time, unless a download is started after which the URL is valid for 12 hours from the start of the download.

It is important to note that the domain and path of this URL might change between API calls, and therefore it's important to use this URL as-is.

Example:

"https://api.box.com/2.0/zip_downloads/Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd/status"

​
expires_at
string<date-time>

The time and date when this archive will expire. After this time the status_url and download_url will return an error.

By default, these URLs are only valid for a few seconds, unless a download is started after which the download_url is valid for the duration of the download, and the status_url is valid for 12 hours from the start of the download.

Example:

"2019-08-29T23:59:00-07:00"

​
name_conflicts
object[][]

A list of conflicts that occurred when trying to create the archive. This would occur when multiple items have been requested with the same name.

To solve these conflicts, the API will automatically rename an item and return a mapping between the original item's name and its new name.

For every conflict, both files will be renamed and therefore this list will always be a multiple of 2.

An individual conflict that occurred when trying to create the archive. This includes an array of 2 objects, each containing the original name and the renamed filename of a file or folder for which the names conflicted.