--- title: "Create zip download" method: POST path: "/zip_downloads" tags: ["Zip Downloads"] --- # Create zip download `POST /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. ## Request body - ZipDownloadRequest — 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. - `type` 'file' | 'folder', required — The type of the item to add to the archive. - `id` string, required — 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`. - `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`. ## Response `202` 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. - ZipDownload — 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. - `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. - `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. - `name_conflicts` array[] — 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. - object[] — 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. - `id` string — The identifier of the item. - `type` 'file' | 'folder' — The type of this item. - `original_name` string — Box Developer Documentation. - `download_name` string — The new name of this item as it will appear in the downloaded `zip` archive. ## Other responses - `400` — 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. - `401` — Returned when the access token provided in the `Authorization` header is not recognized or not provided. - `403` — Returned when an authorization header is provided but the user does not have access to the items. - `default` — An unexpected client error. --- [API](https://skmtc.net/box/apis/platform-api.md) · [All operations](https://skmtc.net/box/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/box/platform-api/versions/ba8f087e1a4d/schema)