Using cache tags

Cache tags let you invalidate groups of related cached content with a single API call, without knowing their exact URLs.

The Problem

When you update a blog post, you need to purge multiple cached pages:

/blog/my-post (the post itself)
/blog (the listing page)
/ (homepage with recent posts)
/author/tim (author archive)
/category/tech (category page)
/feed.xml (RSS feed)

With URL-based purging, your CMS must track every affected URL. That's brittle and error-prone.

How Cache Tags Work

Your origin adds a header listing tags when responding:

Cache-Tag: post-123, author-tim, category-tech

Edgelin stores these tags with the cached response. When post 123 is updated, your CMS calls:

curl -X POST "https://example.com/.cache/purge-tags?key=YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["post-123"]}'

Every cached object tagged with post-123 is invalidated—regardless of URL.

Setting Cache Tags

Add the Cache-Tag header to your origin responses. Tags can be comma or space-separated:

Cache-Tag: post-123, author-tim, category-tech

We also support Fastly's Surrogate-Key header for compatibility:

Surrogate-Key: post-123 author-tim category-tech

WordPress Example

// In your theme's functions.php
add_action('template_redirect', function() {
    if (is_single()) {
        $post = get_post();
        $tags = ['post-' . $post->ID];
        $tags[] = 'author-' . $post->post_author;
 
        foreach (wp_get_post_categories($post->ID) as $cat_id) {
            $tags[] = 'category-' . $cat_id;
        }
 
        header('Cache-Tag: ' . implode(', ', $tags));
    }
});

Laravel Example

return response($content)
    ->header('Cache-Tag', "post-{$post->id}, author-{$post->author_id}");

API Endpoints

Purge by Tags

POST /.cache/purge-tags?key=YOUR_SECRET
Content-Type: application/json
 
{"tags": ["post-123", "author-tim"]}

Response:

{
  "status": "ok",
  "tags": ["post-123", "author-tim"],
  "ram_deleted": 12,
  "disk_deleted": 12,
  "duration_ms": 3
}

View Tag Statistics

GET /.cache/tags?key=YOUR_SECRET

Response:

{
  "status": "ok",
  "tags": {
    "post-123": 3,
    "author-tim": 15,
    "category-tech": 8
  },
  "count": 3
}

Common Tag Patterns

Pattern	Use Case
`post-123`	Specific content item
`author-tim`	All content by an author
`category-tech`	All items in a category
`product-sku-ABC`	Product and its variants
`tenant-acme`	Multi-tenant isolation
`deploy-v2.4`	Invalidate on deployment

Limits

Maximum 64 tags per cached response
Maximum 128 characters per tag
Maximum 100 tags per purge request
Tags cannot contain commas or whitespace

Cluster Support

Tag purges automatically propagate to all cluster nodes. The initiating node broadcasts the purge request to peers, ensuring consistent invalidation across your infrastructure.

Best Practices

Be specific — Use unique identifiers like post-123 rather than generic tags like blog
Layer tags — Combine specific (post-123) with categorical (category-tech) tags
Keep tags short — Shorter tags use less memory in the index
Purge surgically — Purge the minimum tags needed rather than broad categories