openapi: 3.1.0 info: title: Box Zip Downloads API description: Needs a description. paths: /zip_downloads: post: operationId: post_zip_downloads summary: Box Create zip download tags: - Zip Downloads x-box-tag: zip_downloads x-box-reference-category: zip_downloads description: >- 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. requestBody: content: application/json: schema: $ref: '#/components/schemas/ZipDownloadRequest' responses: '202': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/ZipDownload' examples: default: value: 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 '400': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/ClientError' '401': description: >- Returned when the access token provided in the `Authorization` header is not recognized or not provided. content: application/json: schema: $ref: '#/components/schemas/ClientError' '403': description: >- Returned when an authorization header is provided but the user does not have access to the items. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /zip_downloads/{zip_download_id}/content: get: operationId: get_zip_downloads_id_content summary: Box Download zip archive tags: - Zip Downloads x-box-tag: zip_downloads x-box-reference-category: zip_downloads description: >- Returns the contents of a `zip` archive in binary format. This URL does not require any form of authentication and could be used in a user's browser to download the archive to a user's device. By default, this URL is only valid for a few seconds from the creation of the request for this archive. Once a download has started it can not be stopped and resumed, instead a new request for a zip archive would need to be created. The URL of this endpoint should not be considered as fixed. Instead, use the [Create zip download](e://post_zip_downloads) API to request to create a `zip` archive, and then follow the `download_url` field in the response to this endpoint. security: [] servers: - url: https://dl.boxcloud.com/2.0 description: |- An opaque server URL for downloading zip downloads. The format of this URL might change over time. parameters: - name: zip_download_id description: The unique identifier that represent this `zip` archive. example: >- Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd in: path required: true schema: type: string responses: '200': description: >- Returns the content of the items requested for this download, formatted as a stream of files and folders in a `zip` archive. headers: Content-Disposition: description: The name of the archive to be downloaded schema: type: string example: attachment;filename="Avatars.zip";filename*=UTF-8''Avatars.zip content: application/octet-stream: schema: type: string format: binary description: >- The binary content of the archive, which will include the items requested for this download. '404': description: >- Returns an error if the ID of this download request is not valid. This error can also be returned if this URL has been called before. To re-download this archive, please create a new request for a zip download. content: application/json: schema: $ref: '#/components/schemas/ClientError' '429': description: >- Returns an error if the number of concurrent zip downloads has been reached for either the user or the enterprise. * `user_too_many_concurrent_downloads` - the maximum of 5 parallel downloads of zip archives per user has been met. * `enterprise_too_many_concurrent_downloads` - the maximum of 10 parallel downloads of zip archives per enterprise has been met. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /zip_downloads/{zip_download_id}/status: get: operationId: get_zip_downloads_id_status summary: Box Get zip download status tags: - Zip Downloads x-box-tag: zip_downloads x-box-reference-category: zip_downloads description: >- Returns the download status of a `zip` archive, allowing an application to inspect the progress of the download as well as the number of items that might have been skipped. This endpoint can only be accessed once the download has started. Subsequently this endpoint is valid for 12 hours from the start of the download. The URL of this endpoint should not be considered as fixed. Instead, use the [Create zip download](e://post_zip_downloads) API to request to create a `zip` archive, and then follow the `status_url` field in the response to this endpoint. parameters: - name: zip_download_id description: The unique identifier that represent this `zip` archive. example: >- Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd in: path required: true schema: type: string responses: '200': description: Returns the status of the `zip` archive that is being downloaded. content: application/json: schema: $ref: '#/components/schemas/ZipDownloadStatus' '401': description: >- Returned when the access token provided in the `Authorization` header is not recognized or not provided. content: application/json: schema: $ref: '#/components/schemas/ClientError' '403': description: >- Returned when an authorization header is provided but the user does not have access to the items. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: >- Returns an error if the ID of this download request is not valid, or if the status of a download is requested before the download has been started. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' components: schemas: ClientError: title: Client error type: object x-box-resource-id: client_error description: A generic error properties: type: description: error example: error type: string enum: - error nullable: false status: description: The HTTP status of the response. example: 400 type: integer format: int32 nullable: false code: description: A Box-specific error code example: item_name_invalid type: string enum: - created - accepted - no_content - redirect - not_modified - bad_request - unauthorized - forbidden - not_found - method_not_allowed - conflict - precondition_failed - too_many_requests - internal_server_error - unavailable - item_name_invalid - insufficient_scope message: description: A short message describing the error. example: Method Not Allowed type: string nullable: false context_info: description: |- A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example. type: object nullable: true properties: message: type: string description: More details on the error. example: Something went wrong. help_url: description: A URL that links to more information about why this error occurred. example: >- https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/ type: string nullable: false request_id: description: |- A unique identifier for this response, which can be used when contacting Box support. type: string example: abcdef123456 nullable: false ZipDownloadStatus: title: Zip download status type: object x-box-resource-id: zip_download_status x-box-tag: zip_downloads x-box-reference-category: zip_downloads description: The status of a `zip` archive being downloaded. properties: total_file_count: type: integer description: The total number of files in the archive. example: 20 minimum: 0 maximum: 10000 downloaded_file_count: type: integer description: The number of files that have already been downloaded. example: 10 minimum: 0 skipped_file_count: type: integer description: |- The number of files that have been skipped as they could not be downloaded. In many cases this is due to permission issues that have surfaced between the creation of the request for the archive and the archive being downloaded. example: 5 minimum: 0 skipped_folder_count: type: integer description: |- The number of folders that have been skipped as they could not be downloaded. In many cases this is due to permission issues that have surfaced between the creation of the request for the archive and the archive being downloaded. example: 5 minimum: 0 state: type: string description: The state of the archive being downloaded. default: in_progress example: succeeded enum: - in_progress - failed - succeeded tags: - name: Zip Downloads