Purging Assets

If you need to remove or update an asset on imgix, you can purge it from our caches. Common reasons for purging an asset are:

1. An out-of-date or unwanted asset is being served through your imgix Source (e.g. need to remove for DMCA compliance).
2. You want to update an asset in your Source, but renaming the file is not an option.

Purging does not remove assets from any of the following, because they are outside of the imgix system:

• Your Source (Amazon S3, Google Cloud Storage, etc.)
• Any third-party CDNs you might use in addition to the imgix CDN
• The end user’s browser cache
• Any ISP caches between imgix and the end user

Because of this, it is still possible for the end user to see an out-of-date asset on occasion. Please contact Support if you need help with purging operations.

Making a Purge Request

Purging removes the asset (e.g. https://assets.imgix.net/dogs.png) from our caches, which then clears out all derivatives as well (https://assets.imgix.net/dogs.png?w=400, etc.). The Origin Image in your Source remains untouched by the purge operation.

1. Remove or replace the asset in your Origin before triggering a purge request. All of the subsequent validation steps depend on your Origin Image status being changed.

2. Call the Purge API using just the base path to the asset, with no parameters (e.g. you.imgix.net/your-image.png). See Purge Request Methods below for different ways to do this. The request will purge all derivatives of this asset, so you don’t have to do each one individually.

   • The API will return a 200 status code if successfully received; this does not mean that the purge has completed yet.

3. Test the result by fetching the asset again.

   • If you removed the asset, you should receive a 404 error.
   • If you replaced the asset, you should get the updated version.

Purges typically complete through the entire imgix system quickly, but we do not guarantee a completion time, so testing is highly recommended.

For more under the hood information on what happens when you purge an asset, please visit the following imgix blog post: What Happens When You Purge an Asset

Purge Request Methods

Purging from the Dashboard

Using the Tools view in the imgix Dashboard is the easiest way to purge an asset. Simply paste the imgix URL of the asset you want to purge in the text box in the Purge Single Asset section and click Purge.

Please make sure to encode unsafe ASCII characters prior to purging. URL encoding replaces unsafe ASCII characters with a ”%” followed by two hexadecimal digits. For example, if your file name contains a space, please make sure to replace the space with a %20. (e.g. https://assets.imgix.net/image file.png should be changed to: https://assets.imgix.net/image%20file.png)

Assets will be purged at the exact path that is specified. The example above will purge https://assets.imgix.net/image%20file.png, but will not purge https://assets.imgix.net/image+file.png.

Purging with curl

If you’re comfortable using the command line, it’s the fastest way to purge an asset. First, find or create an API key on the API Keys page. The API key must have the Purge permission. Then simply plug it, and the URL of the asset you want to purge, into the example below.

curl -X POST 'https://api.imgix.com/api/v1/purge' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/vnd.api+json' \
  --data-raw '{ "data": { "attributes": { "url": "<url-to-purge>" }, "type": "purges" } }'

Purging with Python

Below is an example of purging an image with Python and the Requests library.

import requests
import json
API_KEY = ""  # API key can be found at https://dashboard.imgix.com/api-keys
API_ENDPOINT = "https://api.imgix.com/api/v1/purge"
imgix_url = "https://assets.imgix.net/examples/couple.jpg"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/vnd.api+json",
}
payload = {
    "data": {
        "type": "purges",
        "attributes": {
            "url": imgix_url,
            "source_id": "5ebee107e9c05c0001d9c2d3",
            "sub_image": False,
        }
    }
}
requests.post(url=API_ENDPOINT, headers=headers, data=json.dumps(payload))

Purging Sub-Images

Images used as a mark or a blend (also called a “sub-image”) need to be purged by including sub-image attributes. The example below performs a purge on the sub-image through the command line.

curl -X POST 'https://api.imgix.com/api/v1/purge' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'Authorization: Bearer <api-key>' \
  --data-raw '{ "data": { "attributes": { "url": "<url-to-purge>", "sub_image": true, "source_id": "<source-id>" }, "type": "purges" } }'

You can read more about the Purging API and see more examples in the Purge API documentation.

Purging Assets Served With the Video API

If you are serving and streaming video using the Video API, the purging service and tools will not work for your video assets.

Instead, to remove or update a video on your site, you can:

• Remove the video from your Origin which will take the video down within 72 hours.
  • To speed up video removal, you can use the Management API’s refresh endpoint to refresh the status on a video that has been removed from your Origin.
• In the case of a DMCA takedown, contact support@imgix.com to take down the video.