11 · Targeted purge and release workflow
Combine versioned URLs, URL/Tag/Prefix/Hostname purge, and verifiable rollback so fresh content ships without creating a zone-wide origin surge.
Edited and verified by Orange Book Editorial Team ·
Release principle
Immutable assets ship under new URLs and generally need no purge. Mutable HTML and APIs invalidate only the affected URL, Tag, Prefix, or Hostname. Purge Everything is an incident tool for an unknown scope, not a standard deployment step.
Select the smallest invalidation scope
| Change | Preferred action | Reason |
|---|---|---|
| Fingerprinted JS/CSS/image | Publish a new URL | Old HTML can keep using the old asset; rollback is simple |
| One article/product | Purge by URL | Cloudflare's recommended precision |
| Related content group | Purge by Cache-Tag | Release automation targets business entities |
| One directory | Purge by Prefix | Good for a clear path boundary |
| One hostname | Purge by Hostname | Independent site or tenant-wide change |
| Incorrect objects with unknown scope | Purge Everything | Widest scope and highest cold-origin cost |
Cloudflare currently exposes URL, Hostname, Tag, Prefix, and Purge Everything on every plan. Rate limits vary by plan and are shared at the account level. Keep the scope small and back off on 429 instead of amplifying it with concurrent retries.
Make invalidation part of the release transaction
flowchart LR
A[Build hashed assets] --> B[Upload new assets]
B --> C[Deploy HTML/API referencing new URLs]
C --> D[Purge only mutable URLs or tags]
D --> E[Verify version, headers, and behavior]
E --> F{Pass?}
F -- Yes --> G[Complete release and monitor]
F -- No --> H[Roll back HTML/API and purge same scope]Upload assets before pages reference them. Purge only after the new content is readable from the origin; otherwise, Cloudflare can drop the old object and cache an error response.
Dashboard and API paths
The dashboard suits occasional manual repair. Continuous delivery should use a least-privilege token and auditable automation. The current Purge API endpoint is:
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/purge_cache" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{"files":["https://www.example.com/docs/changed-page"]}'Grant only the Cache Purge permission required for the target zone. Store the token in a CI secret, never in the repository, logs, or an AI conversation. Test against a non-production zone and retain request scope, release time, and the API response.
Common request bodies:
{"tags":["post:42","category:guides"]}{"hosts":["www.example.com"]}{"prefixes":["www.example.com/docs/"]}Do not combine the examples into one request. Use the invalidation type that matches the release object and follow current operation and rate limits.
Custom-key invalidation trap
If a key contains a Header, Cookie, device, country, or language, sending only the URL can leave variants behind. The Cloudflare API can associate the file URL with headers that formed the key. Release automation must retain a variant inventory or use a Tag/Prefix design that covers the object set.
Purge does not recall browser cache
Cloudflare Purge affects Cloudflare cache layers. It cannot remotely delete an object that a user's browser still considers fresh. Mutable resources need a short Browser TTL; long Browser TTL belongs only on content-hashed URLs.
Verification around a release
Capture version evidence
Record build ID, asset hash, target URL, expected Cache-Tag, current ETag, and body hash.
Upload and verify origin availability
Confirm assets exist and HTML/API references the correct version before purging. Do not disable TLS or WAF or remove privacy headers to make a release test pass.
Purge the smallest set
Use URL for a page, Tag for an entity group, and Prefix for a clear directory. Batch operations and apply jittered exponential backoff to rate limits.
Check from two locations
Save CF-Cache-Status, Age, ETag, Cache-Control, body hash, and CF-Ray from repeated requests. Then use a real browser to check local cache and Service Worker state.
Rehearse rollback
Restore the previous HTML/API and use the same targeted invalidation scope. Fingerprinted assets remain available for clients that still reference the old release.
Next, use Tiered Cache and Cache Reserve to reduce origin pressure from releases and regional cold caches.
Primary sources
Did this page help you complete your goal?
Beta feedback is generated in this browser and is never uploaded automatically.
10 · Cache keys and cache security
Decide which query parameters, headers, cookies, and user dimensions truly change a response to prevent fragmentation, cross-user reuse, and web cache poisoning.
12 · Tiered Cache, Cache Reserve, and origin shielding
Consolidate multi-region misses with Smart Tiered Cache, then decide whether object lifetime and economics justify a persistent Cache Reserve layer.