Cloudflare’s "Purge Everything" button is a blunt instrument. It feels like nuking your entire website’s cache when all you really needed was to update a single image. The good news is you can be surgically precise.
Let’s see selective purging in action. Imagine you just updated https://example.com/images/logo.png. You don’t want to clear everything, just that one file.
curl "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/purge_cache" \
-X POST \
-H "X-Auth-Email: <YOUR_EMAIL>" \
-H "X-Auth-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
--data '{"files": ["https://example.com/images/logo.png"]}'
This curl command targets the Cloudflare API. You’ll need your <ZONE_ID>, your Cloudflare account email (<YOUR_EMAIL>), and your Global API Key (<YOUR_API_KEY>). The files array in the JSON payload is where you list the exact URLs you want to purge. Cloudflare will then hit its edge servers and invalidate the cache for precisely those URLs. It’s that direct.
You can also purge by tag. If you’ve tagged resources with, say, new-design, you can purge them all at once.
curl "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/purge_cache" \
-X POST \
-H "X-Auth-Email: <YOUR_EMAIL>" \
-H "X-Auth-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
--data '{"tags": ["new-design"]}'
This is incredibly useful for managing content updates that affect multiple pages or assets. For instance, if you roll out a new site-wide theme, tagging all associated assets with site-theme-v2 and then purging that tag ensures a consistent update across your entire audience.
The core problem Cloudflare’s cache solves is reducing latency and origin server load. By storing copies of your content closer to your users (at Cloudflare’s edge network), requests don’t have to travel all the way back to your origin server every single time. This dramatically speeds up load times for repeat visitors and reduces the bandwidth and processing demands on your hosting. However, this caching mechanism creates a challenge: how do you update content when it’s sitting in potentially hundreds of distributed cache locations? That’s where selective purging comes in.
The API endpoint /zones/<ZONE_ID>/purge_cache is the gateway. It accepts POST requests with a JSON body. You can specify what to purge using one of three keys: files, prefixes, or tags.
files: An array of exact URLs. This is the most granular.prefixes: An array of URL prefixes. This purges all URLs starting with that prefix. For example,["https://example.com/blog/"]would purgehttps://example.com/blog/post-1,https://example.com/blog/category/tech, and so on. It’s less granular thanfilesbut more thantags.tags: An array of custom tags you’ve applied to your cache. This is powerful for managing content that isn’t easily defined by URL structure.
Understanding the difference between files and prefixes is key. If you update https://example.com/products/widget-x.html, purging https://example.com/products/ as a prefix would also clear https://example.com/products/widget-y.html, which you might not have intended. Using files for https://example.com/products/widget-x.html is the safer, more precise approach.
When you initiate a purge request via the API, Cloudflare doesn’t immediately delete the cached files from every edge server. Instead, it marks those files as "stale." The next time a user requests that specific file, the edge server will check with your origin server for a fresh copy. If your origin server returns a 304 Not Modified or the same content, the edge server will cache the new version. If your origin server returns new content, the edge server caches that. This process ensures that you don’t accidentally force a full revalidation of your entire site, but rather just for the specific assets you’ve targeted.
The most surprising thing about selective purging is how it interacts with Cloudflare’s aggressive edge caching strategies. If you purge a file by URL, Cloudflare will invalidate it. However, if that same file is also covered by a prefix purge or a tag purge that happens after your individual file purge, the subsequent purge might re-cache the old version until the next explicit purge. The order of operations and the scope of your purge requests matter more than you might initially assume. It’s not just about telling Cloudflare what to remove, but also how it’s been categorized for removal.
The next hurdle you’ll likely encounter is managing these API calls programmatically as part of your deployment pipeline or content management system.