Invalidating Cache

Varnish CDN provides a way to invalidate cached content using purge requests. This allows you to remove specific content from the cache when it has been updated or is no longer valid. For example if the origin has updated content, the cache might still serve the old content until it expires based on the caching rules. By sending a purge request, you can ensure that the updated content is served to users immediately.

Varnish CDN has an optimised way of removing cached content based on keys.

Purge Requests

A purge request is basically an HTTP request with the PURGE method. When a purge request is sent to Varnish CDN, it will look for cached content that matches the specified keys and remove it from the cache.

To purge content, you need to send a PURGE request to the Varnish CDN purger endpoint. The request must include the tree, host or path or a combination of host and path (hostpath). As well as the appropriate authentication headers using a Purge Token (see Purge Tokens for more information).

The URL to purge content is in the following format:

https://purger.varnish-cdn.com/api/v1/invalidations/basic/<your-domain>

Where <your-domain> is one of the domains you access to via your Varnish CDN service. The reason for having a domain in the URL is that some systems do not support custom headers and the domain is needed to route the purge request to the correct service.

Purge Keys

The keys used to identify the cached content to be purged are specified in the X-Vcdn-Keys header. The keys can be a combination of host and path called hostpath or tree. The key and the value are separated by a colon (:). For example, to purge a specific path on a domain, you can use the following header:

X-Vcdn-Keys: path:/content/my-image.png

This will purge the cached content for the path /content/my-image.png on the specified domain. To purge all content for a specific domain, you can use the following header:

X-Vcdn-Keys: host:www.example.com

This will purge all cached content for the domain www.example.com. You can also combine both host and path to purge a specific path on a specific domain:

X-Vcdn-Keys: hostpath:www.example.com/content/my-image.png

This will purge the cached content for the path /content/my-image.png on the domain www.example.com.

It is also possible to combine multiple keys in a single purge request by separating them with commas:

X-Vcdn-Keys: host:www.example.com,host:www.another-domain.com
X-Vcdn-Keys: hostpath:www.example.com/content/my-image.png,hostpath:www.another-domain.com/content/another-image.png
X-Vcdn-Keys: tree:/documents/,tree:/images/

The purge key tree is a more broad approach to purge all content within a given path. For example, to purge all content under the /content/ path, you can use the following header:

X-Vcdn-Keys: tree:/content/

Purging by Tag

In addition to path, host, hostpath and tree, you can purge content by any custom tag that your origin has assigned to it (see Assigning Tags from Your Origin below). Unlike the other key types, tag keys have no prefix — you simply use the exact tag string your origin sent, for example:

X-Vcdn-Keys: product-123

This will purge all cached content that was tagged with product-123, regardless of which paths it was served from. You can mix tags with the other key types in the same request:

X-Vcdn-Keys: product-123,path:/content/my-image.png

Assigning Tags from Your Origin

To purge by tag, your origin first needs to tell Varnish CDN which tags apply to a piece of content. It does this by including a ykey response header on the origin response, containing one or more tags separated by spaces or commas:

ykey: product-123 category-shoes

Varnish CDN will remember that this cached response is tagged with both product-123 and category-shoes. Later, a purge request using either tag as a key (as shown in Purging by Tag) will remove it from the cache.

Tags can be any string you choose — there's no required format or prefix, and you're free to design your own tagging scheme (for example, tagging by product ID, category, author, or template). Tags are automatically scoped to your service, so the same tag name used by another Varnish CDN customer will never collide with yours.

Examples

Examples using curl (replace <your-jwt-token> with the actual token and <your-domain> and <path-to-purge> with the appropriate values).

Purge specific path

export PURGER_URL="https://purger.varnish-cdn.com/api/v1/invalidations/basic" \
curl -X PURGE "$PURGER_URL/<your-domain>/<path-to-purge>" \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "X-Vcdn-Keys: path:/content/my-image.png" \

Purge entire domain

export PURGER_URL="https://purger.varnish-cdn.com/api/v1/invalidations/basic" \
curl -X PURGE "$PURGER_URL/<your-domain>" \
    -H "Authorization: Bearer <your-jwt-token>" \
    -H "X-Vcdn-Keys: host:www.example.com" \

Purge specific path on specific domain

export PURGER_URL="https://purger.varnish-cdn.com/api/v1/invalidations/basic" \
curl -X PURGE "$PURGER_URL/<your-domain>/<path-to-purge>" \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "X-Vcdn-Keys: hostpath:www.example.com/content/my-image.png" \

Purge using tree

export PURGER_URL="https://purger.varnish-cdn.com/api/v1/invalidations/basic" \
curl -X PURGE "$PURGER_URL/<your-domain>" \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "X-Vcdn-Keys: tree:/content/" \

Purge by tag

export PURGER_URL="https://purger.varnish-cdn.com/api/v1/invalidations/basic" \
curl -X PURGE "$PURGER_URL/<your-domain>" \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "X-Vcdn-Keys: product-123" \

Invalidation Using Dashboard

It is also possible to invalidate cache using the Varnish CDN dashboard. This can be useful for quick invalidations without needing to set up purge requests. To invalidate cache using the dashboard, follow these steps:

1. Log in to the Varnish CDN dashboard.
2. Navigate to the "Services" section and select the service you want to invalidate cache for.
3. Click the "Purge" drop-down.
4. Choose either "By Path" or "All cache" depending on your needs.
5. Follow the instructions to complete the invalidation.