# Purgar la caché

> Borra contenido cacheado por URL, prefijo, nombre, Cache-Tag o todo; los nodos lo aplican en un segundo. Incluye la purga desde CI con un token de solo purga.

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](https://developers.openwaf.dev/es/cache/cache-tags/). |

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](#ci).

**Panel**

1. Ve a **Caché › Purgar caché**.
2. Pulsa **Purgar todo**, o **Purga personalizada** y elige **Purgar por** (URL, Prefijos, Nombres o Etiquetas); después escribe los valores, uno por línea.
3. Pulsa **Revisar**: el diálogo muestra los valores tal como los normalizó la API, más cualquier aviso.
4. Pulsa **Purgar**. En **Purgas recientes** verás su **Propagación**: nodos que la aplicaron sobre el total de nodos de caché.

**CLI**

```sh
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 nodos
```

La 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).

**API**

```sh
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`):

```sh
curl -s "https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/cache/purges?limit=10" \
  -H "Authorization: Bearer $OPENWAF_TOKEN"
```

**MCP**

`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.

```json
{"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:

1. 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.
2. Guarda el token como un secreto llamado `OPENWAF_PURGE_TOKEN` en tu CI, nunca en el repositorio.
3. Lanza la purga cuando la versión nueva ya esté publicada:

   ```sh
   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](https://developers.openwaf.dev/es/fundamentals/api-tokens/).

> **Consejo**
>
> En sitios con recursos de build con hash (Next.js y similares), purga solo las páginas HTML (`prefixes` o `files`) tras un despliegue. Los recursos del build anterior siguen en caché para las pestañas que siguen abiertas.


## Auditoría

Cada purga queda en la auditoría como `zone.cache.purge`, con su tipo, valores, número y motivo.