openapi: 3.1.0 info: title: Box Authorize Authorization Zip Downloads API description: Needs a description. tags: - name: Zip Downloads description: 'Zip downloads represent a successful request to create a ZIP archive with files and folders.' x-box-tag: zip_downloads 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: ZipDownloadRequest: title: Create a `zip` archive type: object description: A request to create a `zip` archive to download required: - items properties: items: type: array description: 'A list of items to add to the `zip` archive. These can be folders or files.' items: type: object description: An item to add to the `zip` archive. This can be a file or a folder. required: - type - id properties: type: type: string description: The type of the item to add to the archive. example: file enum: - file - folder id: type: string description: '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`.' example: '12345' download_file_name: type: string description: '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 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 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 ZipDownload: title: Zip download type: object x-box-resource-id: zip_download x-box-tag: zip_downloads x-box-reference-category: zip_downloads description: 'Represents a successful request to create a `zip` archive of a list of files and folders.' 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 properties: download_url: type: string description: '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: type: string description: '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: type: string format: date-time description: '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: type: array description: '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.' items: type: array description: '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.' items: type: object description: A file or folder for which a conflict was encountered, This object provides the type and identifier of the original item, as well as a mapping between its original name and it's new name as it will appear in the archive. properties: id: type: string description: The identifier of the item example: '12345' type: type: string description: The type of this item example: file enum: - file - folder original_name: type: string description: The original name of this item example: Report.pdf download_name: type: string description: 'The new name of this item as it will appear in the downloaded `zip` archive.' example: 3aa6a7.pdf