Batch delete files with the API

You can easily delete thousands of files or folders with the batch delete API.

The batch delete API command is one of 40 commands available in the Sirv REST API.

About the delete API

You can delete up to 1000 paths per API request. Each path could be a file or folder. If deleting a folder, all its contents will be deleted, including its files and any subfolders.

If you need to delete more than 1000 paths, submit multiple requests with up to 1000 in each one.

The API endpoint is https://api.sirv.com/v2/files/batch/delete and usage instructions are below.

How to delete multiple files or folders

1. First, you should connect to the Sirv API, to obtain a bearer token.

2. Once you have a bearer token (looks like this but longer: eyJhbGciOiJIUzI1NiI...bGllbnRb2YifQ.wVDr3KMBHIyD5i98emWhx1bEfN3xknCD-r4), you can submit a batch delete API request. The following example uses Curl (visit the batch delete API docs for examples in Python, Node.js, JavaScript, Java, PHP, Ruby, Swift, Go and C#):

curl --request POST 
  --url https://api.sirv.com/v2/files/batch/delete
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiI...bGllbnRb2YifQ.wVDr3KMBHIyD5i98emWhx1bEfN3xknCD-r4'
  --header 'Content-Type: application/json'
  --data '{
    "filenames": ["/Example_folder", "/my-file.jpg", "/Here is a/Sub-Folder"]
}'

Each filename should start with a slash / representing the root of your Sirv account. Each filename should be wrapped in quotation marks " " and separated with a comma ,.

3. If your request was successful, you will receive an ID in the response, such as this:

{
  "id": "Gbycla6K12E2hx5H4ZGFqpNY681VKwbj"
}

4. It normally takes less than 10 seconds to delete up to 1000 files. It can take minutes to delete huge numbers of files. To check the progress of your request, submit the ID in a GET request, like so (example using Curl):

curl --request GET 
  --url 'https://api.sirv.com/v2/files/batch/delete?id=Gbycla6K12E2hx5H4ZGFqpNY681VKwbj' 
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiI...bGllbnRb2YifQ.wVDr3KMBHIyD5i98emWhx1bEfN3xknCD-r4'
  --header 'Content-Type: application/json'

You will see the progress completed percentage:

{
  "progress": 30
}

Once deletion has completed, the response progress will show 100%, like so:

{
  "progress": 100,
  "result": {
    "skipped": [],
    "notfound": 0,
    "deleted":
    {
      files: 2482,
      dirs: 172
      }
    }
  }
}

The result will show how many files and folders (dirs ) were deleted.

If any files or folders had been locked from editing, they will be skipped and shown in the skipped section.

If any files or folders in your request do not exist, they will counted in the notfound section. A common cause for that is the wrong folder path - keep in mind that all paths should start with a leading / slash.

How to handle limits

Batch deletion requests are limited in the following ways:

• Maximum 10 requests per hour
• Maximum 1000 file or folder paths per request
• Maximum 32 KB body size per request

The body of your request is the data section, containing the list of paths to be deleted. The maximum size of 32 KB is equal to 32,768 characters, which is a very large number but your request will exceed this if you try to delete 1000 files with an average path longer than 29 characters (at least 3 characters are required to separate each path). If your request exceeds 32 KB, you will receive a 413 error response "Request Entity Too Large".

To avoid hitting the 32 KB body limit, delete a smaller number of files at a time e.g. 200 or 300. Alternatively, you could count the number of characters in your list of files and submit requests with fewer than 32,768 characters in the body.

The following request is 141 characters, including spaces. It will delete 1 folder and 2 files:

{
  "filenames": ["/Example/folder/", "/Products/19568269/19568269.mp4", "/Main_Folder/Sub-folder/SKU-abc123/My-product-name-abc123-01.jpg"]
}

API testing tools

To test any of Sirv's REST API commands, you might like to use Sirv's swagger.json URL or add the Sirv Postman API collection for use in Postman, Firecamp and other API testing programs.

Get help

Please send any API questions to the Sirv customer success team. We reply to all messages within 24 hours.