Zip files with the API

Use the API to create a zip of files and folders. That zip file could then be downloaded.

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

Choose files for the zip

Before using the zip API, you might like to use the search API to identify which files to include in your zip. The search API let's 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.

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 will receive a JSON response - take note of its job ID, which you will need later:

{
  "id": "J8F9POmzKuRqyjAMUH1ZoEFAFsS41HeH"
}

The zip is now being prepared.

It could take many minutes to create your zip(s) if there is a very large number of files or if there are other zip jobs queued for processing. You can check the status of your job.eep checking the current job status to see if the zip has been created yet.

Check status of job

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

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 succeeds, 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 the ZIP file from the URL in the response. Zips will be deleted after 5 days.

3. If your job succeeds and is greater than 3 GB, a multi-volume zip will be created. This is a special zip made of up to 10 parts (volumes). For example, 30 GB of data would be prepared as 10 volumes of 3 GB each and 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": 3145728,
      "url": "https://goto.sirv.com/gghklzWJDlPkNJXYEMuP4Ps8seCIejhf"
    },
    {
      "filename": "My-bunch-of-files.zip",
      "size": 3971067,
      "url": "https://goto.sirv.com/sgKAlzWJDlPuNJXYEMuP4P08seGIexc9"
    }
  ]
}

All parts must be downloaded in full, then the master file ending .zip should be unzipped. 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.

4. If your job fails, the response will be 400 error (Bad Request). The cause of the failure will be provided in the response, for example, "Too many files" means that the total number of files to be zipped exceeded the limit, so you should try zipping a smaller number of files.

Exclude file/folder

You can exclude certain files or folders by specifying their path, prefixed by a minus - character. The following 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 Sirv Export.zip"
}'

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.