Skip to content

Purging the CDN from your site

The Purge Cache button on a site's CDN page clears the whole CDN cache by hand (see CDN and Shield). When you want the same thing to happen automatically — at the end of a deploy script, or after a bulk content import — you can request the purge from inside the site, with one HTTP request and no API key.

Before you start

  • A site whose CDN is active.
  • A shell on the site: an SSH connection or Cloud Shell (see Accessing your files), or code running in the site itself.

What your site already has

Every site is given two environment variables that authorize the request. You don't need to create or copy any credentials.

Variable What it holds
METADATA_SERVICE The address of the platform's metadata service, http://metadata.internal:8500.
METADATA_AUTH A token that identifies your site. The platform works out which site to purge from this token alone.

Both are set in an SSH or Cloud Shell session, so the examples below work as-is there. PHP code running in the site, such as a plugin, can read them with getenv().

Cron jobs don't receive these variables

A job in the site's crontab file runs with an almost empty environment, so $METADATA_SERVICE and $METADATA_AUTH are blank there and the request fails.

Purge the whole site

curl -sS -X POST "$METADATA_SERVICE/v1/actions" \
  -H "Authorization: Bearer $METADATA_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"action_type":"cdn_purge","params":{"mode":"all"}}'

Purge specific paths

Send "mode": "paths" with a list of up to 100 paths:

curl -sS -X POST "$METADATA_SERVICE/v1/actions" \
  -H "Authorization: Bearer $METADATA_AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "cdn_purge",
    "params": {
      "mode": "paths",
      "paths": ["/blog/hello-world", "/wp-content/uploads/*", "/shop/"]
    }
  }'

Each path is joined to the site's CDN hostname:

  • A path that ends in / or contains * purges everything under it — in the example, all of /wp-content/uploads/ and all of /shop/.
  • Any other path purges exactly that one URL.
  • A missing leading / is added for you.

Sometimes the whole site is purged instead

If Request hostname is turned on under Vary Cache on the site's CDN page, or the site has no CDN hostname, a paths request purges the whole cache.

What comes back

A successful request returns 202 Accepted:

{"id":"3f0c9a1e-5b7d-4c2a-9e61-0d8f2b4a7c13","status":"pending"}
Status Meaning
202 The request was recorded. The platform will pick it up.
400 The body isn't valid JSON, action_type is missing or longer than 128 characters, or params is larger than 64 KB.
401 The Authorization header is missing, or the token isn't recognized.
429 Too many requests. Each site can send a burst of 20, then 2 per second.

Errors come back as {"error": "…"}.

A 202 is not a confirmation

202 only means the request was recorded. The purge itself runs a little later, and nothing is sent back to your site to say whether it ran. The mode and paths values aren't checked when you send the request either — an invalid mode, an empty paths list, or more than 100 paths is dropped later without an error reaching you. A site without an active CDN is likewise skipped silently.

Check that the purge ran

A purge that goes ahead appears on the site's Activity page as Purge CDN Cache, with System in the Performed by column. Its status shows whether it finished (OK) or failed. See Site activity.

Next steps