Box Zip Downloads API

openapi: 3.1.0
info:
  version: "1.0"
  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