---
title: "Caching, revalidation and cache priming"
url: "https://developers.contentstack.com/guides/launch-edge-functions-redirects-and-caching/caching-revalidation-and-cache-priming"
type: "guide_chapter"
level: "intermediate"
intent: "ship"
outcome: "Your pages are cached on the Launch CDN with explicit headers, refreshed by tag or path when content is published, and your key routes are warm after each deployment."
prerequisites:
  - "A Launch environment serving SSR or static pages"
  - "A Contentstack stack with publish webhooks or Automations access"
  - "A Launch API token with the launch:manage or launch.projects:write scope"
next:
  - "https://developers.contentstack.com/guides/launch-edge-functions-redirects-and-caching/logs-debugging-and-limits"
tags:
  - "headless"
  - "api"
  - "automation"
  - "next"
authors:
  - "Tim Benniks"
published: "2026-11-15T10:15:09.438Z"
updated: "2026-11-15T10:55:28.112Z"
---

# Caching, revalidation and cache priming

- **Authors:** Tim Benniks
- **Published:** 2026-11-15T10:15:09.438Z
- **Updated:** 2026-11-15T10:55:28.112Z
- **Level:** Intermediate
- **Intent:** Ship
- **Tags:** headless, api, automation, next

---

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:

```text
Cache-Control: public, max-age=0, s-maxage=86400, stale-while-revalidate
```

The 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:

```typescript
// app/blog/[slug]/page.tsx
export const dynamic = 'force-dynamic';
```

```javascript
// 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:

```typescript
// 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](/guides/launch-edge-functions-redirects-and-caching/edge-functions-in-practice) 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.

```bash
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](/guides/automate-recipe-for-content-type-propagation) 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:

```typescript
// 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.

sequenceDiagram  participant Editor  participant CMS as Contentstack  participant App as /api/revalidate on Launch  participant API as Launch API  participant CDN as Launch CDN  Editor->>CMS: Publish entry  CMS->>App: Webhook (entry, content type)  App->>API: POST revalidate-cdn-cache (path or tags)  API->>CDN: Purge matching entries  Note over CDN: Next request is a miss and goes to the origin## 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:

```bash
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:

```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?](/blog/revalidate-prime-or-redeploy-picking-the-right-cache-lever-on-launch).

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





---

## Do this with AI

Install the launch-platform skill from [Contentstack agent skills](https://github.com/contentstack/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](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

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



---

## Chapter Navigation

**← Previous:** [Edge functions in practice](https://developers.contentstack.com/guides/launch-edge-functions-redirects-and-caching/edge-functions-in-practice)

**Next →:** [Logs, debugging and limits](https://developers.contentstack.com/guides/launch-edge-functions-redirects-and-caching/logs-debugging-and-limits)
