Browser caching & query strings
Two general-settings groups control how content is cached: browser caching (the Cache-Control TTL sent to visitors) and query string handling (which query parameters are part of the cache key). Both live in the property's General tab.
Browser caching
The browser_caching setting decides whether the cache TTL comes from your origin or is overridden by the panel.
mode | Panel label | Behavior |
|---|---|---|
origin | Origin Controlled | Pass the origin's caching headers through unchanged. |
override | Panel Controlled (Override) | Force a fixed TTL regardless of the origin. |
When mode is override, set ttl (in seconds). The default is 3600. The TTL dropdown offers these presets:
| Preset | Seconds |
|---|---|
| 5s | 5 |
| 30s | 30 |
| 2m | 120 |
| 5m | 300 |
| 1h | 3600 |
| 1d | 86400 |
| 1w | 604800 |
| 1mo | 2592000 |
| 1y | 31536000 |
{
"browser_caching": { "mode": "override", "ttl": 3600 }
}
When mode is not override (that is, origin), ttl is saved as 0. The TTL value is only meaningful in override mode.
Query strings
The query_string setting controls how query parameters affect the cache key — whether two URLs that differ only by query string are treated as the same cached object.
mode | Panel option | Effect |
|---|---|---|
none | (off) | Default behavior; query string not stripped from the key. |
ignore_all | "Ignore All" | Ignore the entire query string when caching. |
except | "Ignore All Except…" | Ignore everything except the parameters in values[]. |
only | "Ignore Only…" | Ignore only the parameters in values[]; keep the rest. |
values[] is a list of parameter names and is only sent for except and only modes.
{
"query_string": { "mode": "except", "values": ["page", "lang"] }
}
The panel UI uses all internally for the "Ignore All" option, but it is saved to the API as ignore_all. The accepted persisted values are exactly none, ignore_all, except, and only.
The critical gotcha: send the full object
General settings are stored as a single snake_case JSONB blob, and the API does not merge partial updates.
A PUT to /general-settings replaces the stored blob. If you send only browser_caching, you risk wiping query_string, hsts, image_optimization, and every other field. The panel always reads the current settings, spreads them, applies your change, and sends the full object back.
When scripting against the API, do the same: GET the current general settings, modify the field you care about, then PUT the entire object.
Related
- Security headers (HSTS & more) — the rest of the general-settings blob, with the same merge caveat.
- Image optimization (WebP) — another general-settings group.
- Cache rules — per-path cache behavior beyond the property-wide defaults.