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	`[]`

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.

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

Cache settings reference

#Cache settings

#Cache rule limits

#Fixed behavior

#Early Hints settings

#Purge API

#CLI

#MCP tools