OpenAPI Specification
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