Cache Invalidation

The Cache Invalidation API provides a set of calls for managing and updating cached content to ensure that applications always deliver the most up-to-date and relevant data to their users.

Cloudflare

When using Cloudflare, an additional WAF (Web Application Firewall) rule must be created to ensure that BAN or PURGE requests from Cloudflare are not blocked. More information on configuring the WAF rule is described in the Cloudflare setup.

Flush-URL

The "Flush-URL" call allows you to clear the cache of a specific URL. Whether it's the homepage or a specific resource that needs to be updated, this API call ensures that the latest version of the content is retrieved from the origin server. The request can be used as follows:

curl -X BAN -H "secret: <Token>" -H "url: /" https://www.example.com/
# OR
curl -X BAN -H "secret: <Token>" https://www.example.com/url_to_invalidate

Flush-File

The "Flush-File" call is designed for cases where specific files in the cache need to be invalidated. This is especially useful for static resources like HTML, CSS, or JavaScript files. The call ensures that a specific file is always fetched fresh from the origin server. The request can be used as follows:

curl -X BAN -H "secret: <Token>" -H "cache-file: 469640790ad5bda4d1cc6a19f6770214.html" https://www.example.com/

The hash of the cache file is returned as a response header if the Debug Header option is enabled.

Flush-Tags

The "Flush-Tags" call introduces a tagging system into cache management. Tags can be associated with cached items using the "x-cache-tags" header. If content related to specific tags needs to be invalidated, this call efficiently achieves that. For example:

curl -X BAN -H "secret: <Token>" -H "tags: foo" https://www.example.com/
# Tags are created through the "x-cache-tags: foo, bar" header.

If multiple tags are to be deleted, a request with a list of tags can be submitted. The tags should be passed as a comma-separated list.

curl -X BAN -H "secret: <Token>" -H "tags: foo,bar" https://www.example.com/

Use cases and ideas for the application of Flush-Tags can be found in the Best Practices documentation.

Flush-All

In certain scenarios, it may be necessary to clear the entire cache. The "Flush-All" call provides a way to delete all cached content and start fresh with data from the origin server. The request can be used as follows:

curl -X BAN -H "secret: <Token>" -H "type: flushall" https://www.example.com/