A purge removes cached objects from every edge node; the next request for them goes to your origin. Edge nodes apply a purge within about a second, and you can see how many nodes have applied it.
Purge types
Each purge has exactly one type and up to 100 values:
| Type | API field | Values | Removes |
|---|---|---|---|
| Everything | purge_everything | true | Everything cached for the zone, on every name. |
| URLs | files | Full URLs, e.g. https://www.example.com/app.css?v=2 | Those URLs, every variant (encodings, image formats, origins). The query string counts. |
| Prefixes | prefixes | host/path, e.g. www.example.com/blog/ | Everything whose URL starts with it, any query. |
| Hostnames | hosts | Names of the zone, e.g. static.example.com | Everything cached for those names. |
| Tags | tags | Cache-Tag values, e.g. product-42 | Every object with one of those tags. |
Every value must belong to the zone, and the zone must be active. A purge isn't versioned configuration: it can't be reverted, and reverting a zone version never brings purged content back.
Purge
You need the tech or admin role, or a purge-only token.
- Go to Caching › Purge cache.
- Select Purge everything, or Custom purge and choose Purge by (URLs, Prefixes, Hostnames or Tags), then enter the values, one per line.
- Select Review: the dialog shows the values as the API normalized them, plus any warning.
- Select Purge. Recent purges shows its Propagation as applied nodes out of the caching nodes.
openwaf-cloud ctl cache purge example.com --everything --reason "deploy"
openwaf-cloud ctl cache purge example.com --url https://www.example.com/app.css --url https://www.example.com/ --reason "new css"
openwaf-cloud ctl cache purge example.com --prefix www.example.com/blog/ --reason "blog"
openwaf-cloud ctl cache purge example.com --host static.example.com --reason "static files"
openwaf-cloud ctl cache purge example.com --tag product-42 --reason "price change"
openwaf-cloud ctl cache purges example.com # recent purges, applied on N of M nodesThe command simulates first, shows the normalized values and warnings (for example "the cache is disabled"), and asks for confirmation (--yes without a terminal, --dry-run only simulates).
curl -s -X POST https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/cache/purge \
-H "Authorization: Bearer $OPENWAF_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Change-Reason: new css" \
-d '{"files": ["https://www.example.com/app.css"]}'The body has the same shape as other CDNs' purge APIs: exactly one of purge_everything, files, prefixes, hosts or tags. files accepts strings or {"url": "…"} objects. The answer has seq (the purge number), kind, the normalized values, created_at and warnings; add ?dry_run=1 to normalize and check without purging. X-Change-Reason is optional (default cache purge).
List recent purges with their propagation (nodes and applied):
curl -s "https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/cache/purges?limit=10" \
-H "Authorization: Bearer $OPENWAF_TOKEN"purge_cache works in two steps: confirm=false (default) returns the normalized purge and warnings, then the same call with confirm=true purges.
{"zone": "example.com", "prefixes": ["www.example.com/blog/"], "reason": "blog", "confirm": false}Limits
Purges are rate limited per organization:
| Purge | Limit |
|---|---|
| Everything, prefixes, hostnames, tags | 10 per minute, bursts of up to 30 |
| URLs | 500 URLs per minute (each URL counts once) |
Over the limit the API answers 429 with code rate_limited and a Retry-After header. A zone that isn't active answers 409 (zone_not_active).
Purge from CI after a deploy
Create a token that can only purge one zone's cache, so your pipeline never holds a token that can change configuration:
In API tokens, create a token with Cache purge only. It needs a domain in Scope and the role Tech. The dashboard then shows ready-to-paste snippets for
curl, GitHub Actions and Coolify.Store the token as a secret named
OPENWAF_PURGE_TOKENin your CI, never in the repository.Call the purge after the new version is live:
curl -fsS -X POST "https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/cache/purge" \ -H "Authorization: Bearer $OPENWAF_PURGE_TOKEN" \ -H "Content-Type: application/json" \ -H "X-Change-Reason: deploy" \ -d '{"purge_everything": true}'
A purge-only token can call only POST …/cache/purge and GET …/cache/purges of its zone; everything else, MCP included, is refused with 403 (token_scope). See API tokens.
Audit
Every purge is recorded in the audit log as zone.cache.purge, with its type, values, number and reason.