HTTP Cache-Control Header Builder
Assemble a valid HTTP Cache-Control response header from its cacheability, freshness and revalidation directives — pick a context preset or toggle directives individually, with a plain-English explanation of each and warnings for combinations that are contradictory or partly redundant, like no-store alongside max-age.
Input
Pick a common context to fill in a curated directive combination, or leave on Custom to toggle directives yourself.
Cacheability
Allow any cache, including shared caches (CDNs, proxies), to store the response — even one that would otherwise be treated as non-cacheable.
Restrict caching to the requesting browser only — shared caches must not store this response.
Allow storage, but force revalidation with the origin before every reuse. Does NOT disable caching, despite the name.
Forbid storing the response anywhere, by any cache. The strictest directive — overrides every other one here.
Freshness
How long the response is fresh, in seconds, for browser and shared caches alike. Leave blank to omit.
Overrides max-age for shared caches (CDNs, proxies) only. Leave blank to omit.
After freshness expires, serve the stale response for up to this many seconds while revalidating in the background. Leave blank to omit.
If revalidation fails (origin error or timeout), serve the stale response for up to this many seconds instead of an error. Leave blank to omit.
Revalidation & Other
Once stale, the response must be revalidated with the origin before reuse — caches may not serve stale data even if the origin is unreachable.
Same as must-revalidate, but binding on shared caches only — browsers are unaffected.
Tells the browser the body will never change while fresh, so it should skip conditional revalidation entirely — even on a manual reload. Meaningless without max-age/s-maxage.
Forbid caches and proxies from modifying the response body (e.g. image recompression) even if they normally would.
Only store this response if the cache understands its status code's semantics — typically paired with no-store.
Output
The full header line, ready to paste into your server response configuration.
| Directive | Effect |
|---|---|
| No data yet | |
Contradictory or partly-redundant combinations — the header still generates, but these directives won't behave the way you might expect together.
Guides
What is the Cache-Control Header Builder?
Cache-Control is the HTTP response header that tells browsers, CDNs and proxies whether a response may be cached, for how long, and how it should be revalidated once it goes stale. It's also one of the easiest headers to get wrong: no-cache doesn't mean "don't cache," no-store silently overrides almost everything else you set alongside it, and s-maxage only matters to shared caches while max-age matters to both. This tool assembles a correct header from individual directives (or a curated preset) and explains, in plain English, exactly what each active directive does — plus flags combinations that contradict or partially cancel each other out.
How to use it
- Pick a Context Preset for a common scenario — API response, static asset, HTML page, or private data — or leave it on Custom to toggle directives yourself.
- In Custom mode, check the Cacheability directives that apply (
public,private,no-cache,no-store), set Freshness lifetimes in seconds (max-age,s-maxage,stale-while-revalidate,stale-if-error), and enable any Revalidation directives you need (must-revalidate,proxy-revalidate,immutable,no-transform,must-understand). - The Cache-Control Header box updates automatically — copy it straight into your server config, CDN rule, or application code.
- Read What Each Directive Does for a plain-English explanation of every directive you've enabled, and check Warnings for anything that contradicts or silently cancels another directive you've set.
Choosing a preset
- API response —
no-store. Dynamic, per-request data that should never be cached by anyone. - Static asset —
public, max-age=31536000, immutable. For files with a hashed or versioned filename (app.a1b2c3.js) — the URL itself changes when the content does, so it's safe to cache for a year and skip revalidation entirely. - HTML page —
no-cache. The URL stays the same but the content can change, so caches may store it but must check with the origin before serving it again. - Private data —
private, max-age=0, must-revalidate. Account pages, carts, or anything user-specific: cacheable only by the browser, and always revalidated.
FAQ
What's the difference between no-cache and no-store?
no-cache allows a cache to store the response, but forces it to revalidate with the origin server before serving it again — it's a "check first" directive, not a "don't cache" one. no-store is the strict version: no cache may store the response at all. Mixing no-store with directives like max-age or must-revalidate isn't invalid, but those directives become meaningless — no-store already prevents any storage for them to apply to.
What's the difference between max-age and s-maxage?
max-age sets the freshness lifetime for every cache — the browser and any shared cache (CDN, proxy) in between. s-maxage overrides that lifetime for shared caches only, letting you cache a response longer (or shorter) at the CDN than in the visitor's own browser. s-maxage on a private response has no effect, since shared caches aren't allowed to store private responses in the first place.
Does immutable mean the response is never revalidated?
Only within its freshness window. immutable tells the browser it can skip conditional revalidation requests entirely — including on a user-triggered reload — for as long as max-age (or s-maxage) says the response is fresh. Once that window ends, normal revalidation rules apply again. Setting immutable without a max-age/s-maxage gives it no freshness window to apply within.
Is Cache-Control the only caching header I need?
It's the primary one for controlling freshness and storage, but validators like ETag and Last-Modified still matter for revalidation requests — they're what a cache sends back to the origin to ask "has this changed?" once max-age expires. To convert a duration into a ready-to-use max-age= value without the seconds arithmetic, use the Cache TTL Calculator. For the equivalent header-building workflow on cross-origin requests, see the CORS Headers Builder.
Privacy
This tool runs entirely in your browser. The directives and values you set are never sent to or stored on our servers.
Use it from code
From 3 credits per callREST API
curl -X POST https://api.iotools.cloud/v1/tool/cache-control-header-builder \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"preset": "staticAsset"
}'Swap in your own key from your account. The tool's fields are the body — no wrapper.
Ask an AI agent
Use the IOTools `cache-control-header-builder` tool (HTTP Cache-Control Header Builder) on this input:
YOUR_INPUT_HEREPaste this at any agent connected to the IOTools MCP server, then add your input.