Zip files with the API

Use the API to create a zip of files and folders. That zip file could then be downloaded. It's perfect for bulk downloading a huge number of files.

The mass download zip API is one of 40+ commands available in the Sirv REST API.

Choose files for the zip

Before using the zip download API, you might like to use the search API to identify which files to include in your zip. The search API lets you create very accurate lists of files, based on the time they were created, modified or last accessed. You can also search by file name, path, size, type, width, height or meta tags.

Alternatively, you can use the read folder API, to get a list of folder contents.

You can also exclude files or folders from being included in the zip. This has many use cases, such as downloading an entire folder but excluding some of its contents.

Zip API methods

There are two API methods for zips:

• POST v2/files/zip - create a zip, script examples
• GET v2/files/zip - check a zip, script examples

How to create a zip file

1. Connect to the Sirv API and get a bearer token using the standard method.

2. Use the bearer token to create a zip by submitting a POST request with v2/files/zip.

The filenames field is required and can contain up to 1000 paths. Each path should start with a forward slash. It could be a folder path /example/folder/, a partial path /my-files/abc or a full file name /my-files/abc-01.jpg. You can also exclude paths.

The zipFilename is optional and lets you set a name for the zip file.

The following Curl example will zip 2 images into a file named My-bunch-of-files.zip:

curl --request POST 
  --url https://api.sirv.com/v2/files/zip 
  --header 'Authorization: Bearer eyJhbGhOhytoGHDlqbhagGFDShdOKU' 
  --header 'Content-Type: application/json' 
  --data '{
	"filenames": ["/my-image.jpg", "/another-image.jpg"],
	"zipFilename": "My-bunch-of-files.zip"
}'

3. You can exclude certain files or folders by specifying their path, prefixed by a minus - character.

The following Curl example will include all items in the folder /Products/ and exclude the folder /Products/Active/:

curl --request POST 
  --url https://api.sirv.com/v2/files/zip 
  --header 'Authorization: Bearer eiDktHualktoGHDlqbhagGFDShaiGV' 
  --header 'Content-Type: application/json' 
  --data '{
    "filenames": ["/Products/", "-/Products/Active/"],
    "zipFilename": "My Active Products.zip"
}'

4. You will receive a JSON response - take note of its job ID, which you will need later:

{
  "id": "J8F9POmzKuRqyjAMUH1ZoEFAFsS41HeH"
}

5. The zip is now being prepared. It could take many minutes to create your zip(s) if it contains a very large number of files or if there are other zip jobs queued for processing.

Next, you should check the status of your job...

Check status of job

Check the status to see if your job is ready or has failed.

1. Submit a GET request v2/files/zip stating the job ID:

curl --request GET 
  --url 'https://api.sirv.com/v2/files/zip?id=J8F9POmzKuRqyjAMUH1ZoEFAFsS41HeH' 
  --header 'Authorization: Bearer eyJhbGhOhytoGHDlqbhagGFDShdOKU'

2. If your job has succeeded, the response will contain 3 things: 100(%) progress, the zip file size (bytes) and the URL to download the zip file.

Example response:

{
  "progress": 100,
  "result": [
    {
      "filename": "My-bunch-of-files.zip",
      "size": 9638475,
      "url": "https://goto.sirv.com/sgKAlzWJDlPuNJXYEMuP4P08seGIexc9"
    }
  ]
}

Download your zip file(s)

1. Download the ZIP file from the HTTP URL in the response. The file must be obtained by a simple HTTP request - there is no API command to request the file.

Zips will remain available to download for 5 days, after which they are deleted.

2. If your job contains more than 3 GB of data, a multi-volume zip will be created. This is a special zip with up to 10 parts (volumes). For example, 30 GB of data would be prepared as 10 volumes of 3 GB each. 160 GB of data would be prepared as 10 volumes of 16 GB each.

Each volume of a multi-volume zip will be shown in the response. The following example has 3 volumes:

{
  "progress": 100,
  "result": [
    {
      "filename": "My-bunch-of-files.z02",
      "size": 3186106,
      "url": "https://goto.sirv.com/sT8hdE4F2hlPP4Ps8seCIejhf4Rrho2r"
    },
    {
      "filename": "My-bunch-of-files.z01",
      "size": 3187404,
      "url": "https://goto.sirv.com/gghklzWJDlPkNJXYEMuP4Ps8seCIejhf"
    },
    {
      "filename": "My-bunch-of-files.zip",
      "size": 2971067,
      "url": "https://goto.sirv.com/sgKAlzWJDlPuNJXYEMuP4P08seGIexc9"
    }
  ]
}

3. Download each file one-by-one, waiting for the file to finish downloading before requesting the next one. If you download multiple files simultaneously, you might hit a limit and the download will fail.

4. Downloads are resumable, so if a partly downloaded file fails, resume it and it will carry on. Otherwise, send a fresh request to download that volume.

5. Once all parts have downloaded in full, unzip the master file ending .zip. Do not extract any of the other volumes ending .z01, .z02 etc.

Visit our article and video tutorial on how to download and unpack multi-volume zips.

Handling an error

If your bulk download API request fails, you will receive a 400 error (Bad Request). In the body of the response will be the cause of the problem.

Possible causes:

• Too many files - the total number of files to be zipped exceeded the limit, so you should try requesting fewer files/folders.
• error,locked - the filesystem did not finish saving your zip. Please report this to the Sirv team.

We recommend logging the responses returned by the API, to help you to troubleshoot any error.

Zip size limit

The total size of files to be zipped is limited. If you hit a limit, reduce the number of files that you're zipping:

* The total number of files is limited to an amount that can be safely handled. The amount is dynamic and very large - typically hundreds of thousands of files. If your request exceeds the limit, you will receive an error 400 (Bad Request), so you should try downloading a smaller number of images at a time.

Support

If you need help with the REST API, please send a message to the Sirv support team.