Do this with AI
Install the launch-platform skill from Contentstack agent skills and connect the Delivery Analytics profile in MCP Profile Hub. Then ask your agent:
Show the cache hit ratio and the most requested uncached URLs for my Launch project over the last 7 days, and suggest which routes need a Cache-Tag or a cache priming entry.
New to this? Set up your AI workbench first.
Caching, revalidation and cache priming
Caching on Launch is plain HTTP. Your origin sends Cache-Control, the CDN follows it, and you decide when to throw entries away. There is no framework-specific cache layer to learn, which also means framework features such as the Next.js App Router Data Cache and revalidatePath() don't apply. This chapter shows the setup that works well for content sites: long CDN lifetimes, targeted purges on publish, and a warm cache after each deployment.
What you'll learn
How to set Cache-Control and Cache-Tag headers in Next.js on Launch
How to purge by path, tag or hostname with the Revalidate CDN Cache API
How to revalidate from Automations or from a webhook when an entry is published
How to configure cache priming in launch.json
Which caching mistakes leak or pin content
Set Cache-Control on the origin
Launch concept: the Launch CDN caches a response for as long as s-maxage (or max-age) allows. max-age controls the browser, s-maxage controls the CDN.
A common setup for content pages:
Cache-Control: public, max-age=0, s-maxage=86400, stale-while-revalidateThe browser always checks with the CDN, and the CDN keeps the page for 24 hours.
In a Next.js App Router project, opt the route out of the Full Route Cache and set the header in next.config.js:
// app/blog/[slug]/page.tsx
export const dynamic = 'force-dynamic';// next.config.js
module.exports = {
async headers() {
return [
{
source: '/blog/:slug*',
headers: [
{ key: 'Cache-Control', value: 'public, max-age=0, s-maxage=86400, stale-while-revalidate' },
{ key: 'Cache-Tag', value: 'prod-blog' },
],
},
];
},
generateBuildId: () => process.env.CONTENTSTACK_LAUNCH_DEPLOYMENT_UID,
};generateBuildId ties the Next.js build to the Launch deployment UID. Launch documents this step for on-demand revalidation, so the CDN refreshes the right build.
Route handlers can set headers per response, which is handy for JSON endpoints:
// app/api/products/route.ts
import { NextResponse } from 'next/server';
export async function GET() {
const products = await getProducts();
const response = NextResponse.json(products);
response.headers.set('Cache-Control', 'public, s-maxage=300');
response.headers.set('Cache-Tag', 'prod-products');
return response;
}If you are on the Pages Router, Launch supports ISR there. The rest of this chapter applies either way.
Know what the cache key is
The cache key is the URL: scheme, hostname, path and query string. Headers and cookies are not part of it. Two consequences:
/page?utm_source=x and /page?utm_source=y are separate cache entries. Strip tracking parameters in an edge function if they fragment your cache.
A page that renders differently per cookie must send Cache-Control: no-store, or move the per-user part to a client-side call. Otherwise one visitor's response is served to everyone.
Purge with the Revalidate CDN Cache API
Launch concept: revalidation tells the CDN to drop cached entries for an environment, across every domain attached to it. The next request goes to the origin.
curl -X POST \
"https://launch-api.contentstack.com/projects/$PROJECT_UID/environments/$ENVIRONMENT_UID/revalidate-cdn-cache" \
-H "Authorization: Bearer $LAUNCH_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "cachePath": { "path": "/blog", "isPrefix": true } }'The body takes exactly one of three inputs:
Input | Example | Purges |
|---|---|---|
cachePath | { "path": "/blog/my-post", "isPrefix": false } | One path, or everything under it with isPrefix: true |
cacheTags | ["prod-blog"] | Every response that carried one of these tags |
hostnames | ["www.example.com"] | Everything for those domains |
Use the base URL for your region, for example https://eu-launch-api.contentstack.com in AWS EU. With an authtoken instead of OAuth, send authtoken and organization_uid headers. A successful call returns "The CDN cache revalidation task has been initiated."
{ "path": "/", "isPrefix": true } clears the whole site without a deployment. You can also purge by path, tag or domain from Settings > Environments > Cache in Launch.
Tags are the efficient option. One request with cacheTags can clear hundreds of URLs. Put an environment prefix in every tag, such as prod-blog and staging-blog, in both the header and the purge request. That way a purge triggered for staging can never touch production pages that share a tag name.
Revalidate when content is published
You have two ways to call the API on publish.
Automations. The Launch connector in Automations has a Revalidate CDN Cache action. Trigger it on entry publish, map the entry URL to the path, and you are done without writing code. The Automate guides show how to build a trigger and action flow.
A webhook handler in your app. If you prefer code, point a Contentstack webhook at a route in your own site and call the API from there:
// app/api/revalidate/route.ts
export async function POST(request: Request) {
if (request.headers.get('x-webhook-secret') !== process.env.WEBHOOK_SECRET) {
return new Response('Unauthorized', { status: 401 });
}
const payload = await request.json();
const contentType = payload?.data?.content_type?.uid;
const url = payload?.data?.entry?.url;
const purge = (body: object) =>
fetch(
`https://launch-api.contentstack.com/projects/${process.env.LAUNCH_PROJECT_UID}/environments/${process.env.LAUNCH_ENVIRONMENT_UID}/revalidate-cdn-cache`,
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LAUNCH_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
}
);
const jobs = [];
if (url) jobs.push(purge({ cachePath: { path: url, isPrefix: false } }));
if (contentType === 'blog_post') jobs.push(purge({ cacheTags: ['prod-blog'] }));
await Promise.all(jobs);
return Response.json({ revalidated: jobs.length });
}Add x-webhook-secret as a custom header on the webhook in your stack settings, and send Cache-Control: no-store from this route if your framework doesn't already. Check the webhook payload of your stack before you rely on data.entry.url. Content types without a url field need a mapping from entry to path.
Stay inside the quota
Revalidation has a daily quota per organization, and calls past it return 429. Check it from your pipeline or a dashboard:
curl "https://launch-api.contentstack.com/usage-analytics/revalidate-cdn-cache" \
-H "Authorization: Bearer $LAUNCH_TOKEN"The response has currentCacheRevalidations, maxCacheRevalidations and a usageReset timestamp. Tags and prefixes keep the count low. A failing automation that sends the same purge on a loop is the usual way teams run out.
Warm the cache with cache priming
Every deployment purges the CDN, so the first visitor to each page after a release waits for the origin. Cache priming requests a list of paths as part of the deployment so they are cached before real traffic arrives.
Add the paths to launch.json:
{
"cache": {
"cachePriming": {
"urls": ["/", "/pricing", "/blog", "/docs"]
}
}
}Then turn on Enable Cache Priming in Settings > Environments > Cache. The setting applies from the next deployment.
Rules for the list:
Use relative paths only. Full URLs, wildcards and regex are not supported, so generate the list at build time if it comes from content.
Only list routes that send a cacheable Cache-Control. A no-store route is requested and logged, but never cached.
Priming requests use the user agent Contentstack-Launch/CachePrimingAgent/1.0. Allow it in your WAF, and filter on it in analytics. Don't use it for authentication.
A route that fails to prime doesn't fail the deployment.
Where people get confused
Long lifetimes on the wrong responses. A one-year s-maxage on HTML is fine when you purge on publish. On a redirect or an error-prone route it pins a mistake at the edge. Purge the path with cachePath to recover.
Counting on stale-while-revalidate. Treat it as a bonus. Size s-maxage and your purge strategy so that pages are fresh without it, and check cf-cache-status and age response headers when you test.
Redeploying to publish content. It works, because a deployment purges the cache, but every publish becomes a full build. Use revalidation for content and deployments for code. The trade-offs are in Revalidate, prime or redeploy?.
Key takeaways
Send public, max-age=0, s-maxage=<seconds> for content pages and no-store for anything that depends on cookies.
Add Cache-Tag headers with an environment prefix, such as prod-blog.
Purge with POST /projects/{project_uid}/environments/{environment_uid}/revalidate-cdn-cache and one of cachePath, cacheTags or hostnames.
Trigger revalidation on publish with the Automations Launch connector or a small webhook route.
List your most visited routes under cache.cachePriming.urls and enable cache priming in the environment settings.
Watch GET /usage-analytics/revalidate-cdn-cache so you don't hit the daily quota.
Frequently asked questions
Does a redeploy clear the Launch CDN cache?
Yes. Every deployment purges the CDN cache of that environment, so a redeploy always serves fresh pages, at the cost of a full build.
Can I send a path and cache tags in one revalidation request?
No. Each request takes exactly one of cachePath, cacheTags or hostnames. Send separate requests if you need more than one.
Why does cache priming not help a page?
Priming only helps routes that return a cacheable Cache-Control header. Routes with no-store, no-cache or must-revalidate are requested but never cached.
Is there a limit on cache revalidations?
Yes, there is a daily revalidation quota per organization. Check your usage with GET /usage-analytics/revalidate-cdn-cache on the Launch API.