Using cache keys

Cache keys let you tag cached responses with arbitrary identifiers and later purge every response sharing a tag in a single request. They’re the right tool when you want to purge a category of content rather than a specific URL — for example, every page belonging to a particular environment, release, content type, or module.

How it works

1. Your origin emits a Cache-Keys response header on responses you want to tag. The value is one or more space-separated keys.
2. QuantCDN tags the cached object with those keys (after hashing them against your project’s namespace) and strips the header so it never reaches the client.
3. Later, you POST /v1/purge with the same Cache-Keys header set, and every cached object tagged with any of those keys is invalidated.

# Example origin response
HTTP/1.1 200 OK
Content-Type: text/html
Cache-Control: public, max-age=3600
Cache-Keys: env:production release:1.4.2 module:linkit

Properties to know

Matching is exact, not wildcard

env:test purges everything tagged exactly env:test. There is no prefix matching — env: will not match env:test, and env:* is treated as a literal string, not a glob. Plan your key names accordingly: if you want to be able to purge “everything related to env X”, emit a single shared key like env:test on every response in that environment.

Keys are isolated per project

You don’t need to namespace your keys with your project name. QuantCDN hashes every key against your organisation and project before storing it in cache metadata, so a key like env:test from your project cannot collide with the same string from another customer’s project. The hashing happens at both ingest and purge time, using your authenticated Quant-Token’s organisation and project — so an attacker cannot forge a key that targets a project they don’t have credentials for.

There is no discovery API

QuantCDN does not currently expose a way to list the cache keys associated with a project or URL. Keys are something you define on your side as a convention — track them in your origin codebase, deployment scripts, or wherever else fits your workflow.

Purges are asynchronous

POST /v1/purge returns immediately with {"status": "accepted"} (or {"status": "success"} for AWS-hosted projects). The actual edge invalidation completes in a few seconds. Don’t rely on the response to mean “cache is empty” — treat it as “purge request accepted.”

Recommended pattern: per-environment purging

A common situation: a single QuantCDN project hosts multiple environments (e.g. test.example.com and www.example.com), and you want post-deploy purges in CI to scope to only the environment that was deployed.

The clean solution is to have each environment’s origin emit an identifying cache key:

# Test environment responses
Cache-Keys: env:test

# Production environment responses
Cache-Keys: env:production

Then your CI purges only the matching key:

- name: Purge test cache
  if: github.ref == 'refs/heads/develop'
  uses: quantcdn/purge-action@v7
  with:
    customer: ${{ secrets.QUANT_CUSTOMER }}
    project: my-project
    token: ${{ secrets.QUANT_TOKEN }}
    cache_keys: env:test

- name: Purge production cache
  if: github.ref == 'refs/heads/main'
  uses: quantcdn/purge-action@v7
  with:
    customer: ${{ secrets.QUANT_CUSTOMER }}
    project: my-project
    token: ${{ secrets.QUANT_TOKEN }}
    cache_keys: env:production

You can extend the same pattern for any axis you want to be able to purge along: release version, content section, feature flag, etc. Stack multiple keys in one header:

Cache-Keys: env:production release:1.4.2 section:blog

A single purge for any of those keys then invalidates this response.

Emitting Cache-Keys from common origins

Drupal

If you use the Quant Drupal integration, the quant_purger module already maps Drupal’s cache tags onto the Cache-Keys header for you.

Next.js / custom Node

Set the header from your route handler or middleware:

app/products/[slug]/page.tsx

export async function GET(request: Request) {
  return new Response(html, {
    headers: {
      'Content-Type': 'text/html',
      'Cache-Control': 'public, max-age=3600',
      'Cache-Keys': `env:${process.env.NODE_ENV} section:products`,
    },
  });
}

Static sites with a build-time header injector

Static hosts that emit per-file headers (e.g. _headers files, hosting configs) can include Cache-Keys alongside cache-control:

/products/*
  Cache-Control: public, max-age=3600
  Cache-Keys: env:production section:products

What to do next

• Purge via the API — the full POST /v1/purge reference, including soft purges.
• Purge via the dashboard — when you want to purge interactively.
• Deploy via CI/CD — wiring purges into a GitHub Actions workflow.