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 to send the purge request to.
METADATA_AUTH A token that identifies your site, so the request purges this site only.

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.

If Request hostname is turned on under Vary Cache on the site's CDN page, or the site has no CDN hostname, a paths purge clears 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 accepted.
400 The body isn't valid JSON, or action_type is missing.
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": "…"}.

Confirm it ran

A 202 means the request was accepted, not that the purge has run. The purge happens shortly after, and a request with invalid values, or for a site without an active CDN, is skipped without an error. To confirm, open the site's Activity page: a purge that ran appears as Purge CDN Cache, with System in the Performed by column, and its status shows whether it finished (OK) or failed. See Site activity.

Next steps