# Cache settings reference

> Every cache and Early Hints setting with its default and limits, the purge API and limits, the CLI commands and MCP tools.

## Cache settings

Keys under `cache` in the zone's edge settings (`GET`/`PATCH /v1/orgs/{org}/zones/{zone}/edge`), overridable per name under `hosts.<name>.cache`.

| Key | Values | Default |
|---|---|---|
| `cache.enabled` | `true`, `false` | `false` |
| `cache.dev_mode_until` | RFC 3339 time, or `null` (off) | off |
| `cache.query.mode` | `all`, `ignore`, `none`, `include`, `exclude` | `all` |
| `cache.query.params` | Parameter names (trailing `*` = prefix); required with `include`/`exclude` | `[]` |
| `cache.query.sort` | `true`, `false` | `false` |
| `cache.browser_ttl` | Seconds, `0`–`31536000`; `0` = respect the origin | `0` |
| `cache.deception_armor` | `true`, `false` | `true` |
| `cache.serve_stale.while_revalidate` | `true`, `false` | `true` |
| `cache.serve_stale.on_error_max_s` | Seconds, `0`–`2592000`; `0` = never | `86400` |
| `cache.max_object_mb` | `1`–`512` | `100` |
| `cache.rules` | Up to 25 [cache rules](https://developers.openwaf.dev/cache/cache-rules/) | `[]` |

The `PATCH` body is a JSON merge patch: objects merge field by field, lists (`rules`, `query.params`) are replaced whole, `"dev_mode_until": null` turns development mode off and `"cache": null` restores every default.

### Cache rule limits

| Item | Limit |
|---|---|
| Rules per zone or per name | 25 |
| Values per condition list | 32 |
| Status ranges per rule | 10, codes 100–599 |
| TTLs (`edge_ttl.ttl_s`, `browser_ttl.ttl_s`, status TTLs) | 1 second to 1 year; status TTLs also `0` (always revalidate) and `-1` (don't store) |
| `serve_stale.on_error_max_s` | Up to 30 days |
| Extension | Letters and digits, up to 16 characters |
| Rule id | Letters, digits, `-` and `_`; default `r1`, `r2`… |

### Fixed behavior

| Item | Value |
|---|---|
| Default TTL without freshness headers | 2 h (`200`, `206`, `301`), 20 min (`302`, `303`), 3 min (`404`, `410`) |
| Framework build directories | 7 days |
| Longest life of an object | 30 days |
| Longest cache key | 4 KB |
| Wait for a concurrent miss of the same object | 5 seconds |

## Early Hints settings

| Key | Values | Default |
|---|---|---|
| `early_hints.enabled` | `true`, `false` | `false` |
| `early_hints.mode` | `origin_links`, `html_head`, `both` | `both` |
| `early_hints.extra_origins` | Up to 10 `https://host[:port]` origins | `[]` |

See [Early Hints](https://developers.openwaf.dev/cache/early-hints/).

## Purge API

| Route | Role | Purpose |
|---|---|---|
| `POST /v1/orgs/{org}/zones/{zone}/cache/purge` | `tech` or purge-only token | Purge. Body: exactly one of `purge_everything`, `files`, `prefixes`, `hosts`, `tags` (≤ 100 values). `?dry_run=1` normalizes without purging. |
| `GET /v1/orgs/{org}/zones/{zone}/cache/purges?limit=N` | any, or purge-only token | Recent purges (newest first, at most 100) with `nodes` and `applied`. |

| Status | Code | When |
|---|---|---|
| `409` | `zone_not_active` | The zone isn't active. |
| `429` | `rate_limited` | Over 10 purges per minute (burst 30) for everything, prefixes, hostnames and tags, or 500 URLs per minute. `Retry-After` says when to retry. |
| `403` | `token_scope` | A purge-only token called any other route. |

## CLI

| Command | Purpose |
|---|---|
| `openwaf-cloud ctl zones set <zone> [--host <name>] cache.…=… early_hints.…=…` | Change cache and Early Hints settings. |
| `openwaf-cloud ctl zones set <zone> --host <name> --unset cache` | The name inherits the zone's cache again. |
| `openwaf-cloud ctl zones effective <zone> <name>` | Effective cache of a name. |
| `openwaf-cloud ctl cache purge <zone> --everything \| --url U… \| --prefix host/path… \| --host name… \| --tag t…` | Purge. |
| `openwaf-cloud ctl cache purges <zone> [--limit N]` | Recent purges and their propagation. |

## MCP tools

| Tool | Purpose |
|---|---|
| `update_settings` | Change `cache` and `early_hints` (with `host` for one name). |
| `effective_config` | Effective configuration of one name, cache included. |
| `purge_cache` | Purge (two steps). |