Una purga borra objetos cacheados de todos los nodos del borde; la siguiente petición de esos objetos va a tu origen. Los nodos del borde aplican una purga en un segundo aproximadamente, y puedes ver cuántos la han aplicado.
Tipos de purga
Cada purga tiene un solo tipo y hasta 100 valores:
| Tipo | Campo de la API | Valores | Borra |
|---|---|---|---|
| Todo | purge_everything | true | Todo lo cacheado de la zona, en todos los nombres. |
| URL | files | URL completas, p. ej. https://www.example.com/app.css?v=2 | Esas URL, con todas sus variantes (codificaciones, formatos de imagen, orígenes). La cadena de consulta cuenta. |
| Prefijos | prefixes | nombre/ruta, p. ej. www.example.com/blog/ | Todo lo que tenga una URL que empiece así, con cualquier consulta. |
| Nombres | hosts | Nombres de la zona, p. ej. static.example.com | Todo lo cacheado de esos nombres. |
| Etiquetas | tags | Valores de Cache-Tag, p. ej. product-42 | Todos los objetos con alguna de esas etiquetas. |
Todos los valores deben ser de la zona, y la zona debe estar activa. Una purga no es configuración versionada: no se puede revertir, y revertir una versión de la zona nunca resucita contenido purgado.
Purgar
Necesitas el rol tech o admin, o un token de solo purga.
- Ve a Caché › Purgar caché.
- Pulsa Purgar todo, o Purga personalizada y elige Purgar por (URL, Prefijos, Nombres o Etiquetas); después escribe los valores, uno por línea.
- Pulsa Revisar: el diálogo muestra los valores tal como los normalizó la API, más cualquier aviso.
- Pulsa Purgar. En Purgas recientes verás su Propagación: nodos que la aplicaron sobre el total de nodos de caché.
openwaf-cloud ctl cache purge example.com --everything --reason "despliegue"
openwaf-cloud ctl cache purge example.com --url https://www.example.com/app.css --url https://www.example.com/ --reason "css nuevo"
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 "estáticos"
openwaf-cloud ctl cache purge example.com --tag product-42 --reason "cambio de precio"
openwaf-cloud ctl cache purges example.com # purgas recientes, aplicadas en N de M nodosLa orden simula primero, enseña los valores normalizados y los avisos (por ejemplo, «la caché está desactivada») y pide confirmación (--yes sin terminal; --dry-run solo simula).
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: css nuevo" \
-d '{"files": ["https://www.example.com/app.css"]}'El cuerpo tiene la misma forma que las API de purga de otras CDN: exactamente uno de purge_everything, files, prefixes, hosts o tags. files admite cadenas u objetos {"url": "…"}. La respuesta trae seq (el número de la purga), kind, los values normalizados, created_at y warnings; añade ?dry_run=1 para normalizar y comprobar sin purgar. X-Change-Reason es opcional (por defecto, cache purge).
Para ver las purgas recientes con su propagación (nodes y applied):
curl -s "https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/cache/purges?limit=10" \
-H "Authorization: Bearer $OPENWAF_TOKEN"purge_cache funciona en dos pasos: confirm=false (por defecto) devuelve la purga normalizada y los avisos, y la misma llamada con confirm=true purga.
{"zone": "example.com", "prefixes": ["www.example.com/blog/"], "reason": "blog", "confirm": false}Límites
Las purgas tienen un límite por organización:
| Purga | Límite |
|---|---|
| Todo, prefijos, nombres, etiquetas | 10 por minuto, con ráfagas de hasta 30 |
| URL | 500 URL por minuto (cada URL cuenta una vez) |
Al superarlo, la API responde 429 con code rate_limited y una cabecera Retry-After. Una zona que no está activa responde 409 (zone_not_active).
Purgar desde CI tras un despliegue
Crea un token que solo pueda purgar la caché de una zona, para que tu pipeline nunca tenga un token capaz de cambiar la configuración:
En Tokens de API, crea un token con Solo purgar la caché. Necesita un dominio en Alcance y el rol Técnico. Después, el panel muestra fragmentos listos para pegar en
curl, GitHub Actions y Coolify.Guarda el token como un secreto llamado
OPENWAF_PURGE_TOKENen tu CI, nunca en el repositorio.Lanza la purga cuando la versión nueva ya esté publicada:
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: despliegue" \ -d '{"purge_everything": true}'
Un token de solo purga solo puede llamar a POST …/cache/purge y GET …/cache/purges de su zona; todo lo demás, MCP incluido, se rechaza con 403 (token_scope). Consulta Tokens de API.
Auditoría
Cada purga queda en la auditoría como zone.cache.purge, con su tipo, valores, número y motivo.