Cache Invalidation
smoxy caches content at the edge to reduce load on your origin server. When content changes, you need to invalidate the cached version so visitors see the update. smoxy provides several methods to do this - from clearing a single URL to flushing entire tag groups.
All invalidation requests use the HTTP BAN method and require the cache token configured in your zone's Proxy.
These BAN requests (the edge also accepts PURGE as an equivalent method) are sent directly to smoxy's edge and are authenticated by your zone's purge token - the core system performs the invalidation itself, with no hub API call required. This keeps framework integrations simple: a Symfony/FOSHttpCache-style cache invalidator only needs to issue BAN requests against your hostname. The hub API's cache-clear endpoints are an additional convenience layered on top of the same mechanism.
INFO
Cloudflare users: Cloudflare may block BAN/PURGE requests. See Cloudflare Setup for the recommended workaround.
Methods
Flush URL
Clears the cache for a specific URL.
curl -X BAN -H "secret: <token>" -H "url: /" https://www.example.com/You can also pass the URL as the request target:
curl -X BAN -H "secret: <token>" https://www.example.com/products/my-productFlush Tags
Clears all cached content tagged with one or more cache tags. Tags are set on your origin's responses using the x-cache-tags header (see Cache for tag configuration).
Flush a single tag:
curl -X BAN -H "secret: <token>" -H "tags: smartphones" https://www.example.com/Flush multiple tags at once (comma-separated):
curl -X BAN -H "secret: <token>" -H "tags: smartphones,accessories" https://www.example.com/When to use tags: Tags are the most efficient way to invalidate groups of related content. For example, if your shop tags product pages with their category name, you can flush all "Samsung" products with a single request instead of purging each URL individually.
Common tagging strategies:
| Strategy | Tag Example | Use Case |
|---|---|---|
| By category | smartphones, laptops | New products added to a category |
| By brand | samsung, apple | Brand-wide price update |
| By product ID | product-123 | Single product changed |
| By page type | listing, detail, home | Template or layout change |
Flush File
Clears a specific cached file by its cache hash. This is useful when you know the exact cache entry to invalidate.
curl -X BAN -H "secret: <token>" -H "cache-file: 469640790ad5bda4d1cc6a19f6770214.html" https://www.example.com/INFO
Tip: The cache file hash is returned as a response header when Debug Headers are enabled.
Flush Content Class
Clears all cached content of a whole class with a single request - images, HTML documents, or static assets. smoxy tags every cached object with its content class automatically, so this works without any origin configuration.
curl -X BAN -H "secret: <token>" -H "type: images" https://www.example.com/type | Clears |
|---|---|
html | All cached HTML documents |
images | All cached images |
assets | All other cached static files (CSS, JavaScript, fonts, ...) |
This is useful when one kind of content changes wholesale - for example, flush images after regenerating thumbnails without touching the cached HTML. Each BAN request performs a single action: send type on its own to clear a content class - it is not combined with tags, url, or cache-file in the same request. The singular forms image and asset are also accepted.
The same content-class purge is also available without a BAN token: through the Clear Cache by Type quick action in the Hub, or over the Hub API by sending POST /api/zones/{zoneId}/cache/clear with action set to html, images, or assets:
curl -X POST https://api.smoxy.eu/api/zones/{zoneId}/cache/clear \
-H "X-API-TOKEN: <token>" \
-H "Content-Type: application/json" \
-d '{"action": "images"}'The response's cdnCleared field reports whether the matching CDN cache was purged as well. This endpoint is limited to one clear per zone every 5 seconds (see Rate Limiting).
Flush All
Clears the entire cache for the zone. Use this as a last resort - it forces every request to be fetched fresh from your origin until the cache warms up again.
curl -X BAN -H "secret: <token>" -H "type: all" https://www.example.com/INFO
type: flushall is the legacy spelling of this request and keeps working.
Choosing the Right Method
| Method | Scope | Speed | Origin Load |
|---|---|---|---|
| Flush URL | Single URL | Instant | Minimal |
| Flush Tags | Group of related pages | Instant | Moderate |
| Flush File | Single cache entry | Instant | Minimal |
| Flush Content Class | All images, HTML, or assets | Instant | Moderate to high |
| Flush All | Entire zone cache | Instant | High (cache cold start) |
Start with the most targeted method. Use Flush URL for single pages, Flush Tags for groups, Flush Content Class for one kind of content, and Flush All only when necessary.
Rate Limiting
BAN/PURGE requests are throttled at the edge. Up to 5 requests per second are processed immediately; above that rate, each additional request is delayed by 100 ms. Requests are never rejected - they are only slowed down.
The hub API's zone cache-clear endpoint - which also powers the Dashboard quick actions - has its own limit: one cache clear per zone every 5 seconds. Requests above that limit are rejected with 429 Too Many Requests and a Retry-After header telling you when to retry.
TIP
Don't clear the whole cache by sending one BAN/PURGE request per URL - large batches will run into the throttle. To invalidate everything, send a single Flush All request (or use the Clear Entire Cache quick action in the Dashboard) - it clears the entire zone cache with one request.
Also, don't trigger Flush All on every request or change. Reserve it for moments where a full invalidation is actually needed: at the end of sync processes (e.g. price and stock updates in an online shop) or after deploying a new release when the cache for all URLs of the app needs to be cleared.
Quick Actions
You can also clear cache without writing code using the Dashboard quick actions:
- Clear Entire Cache - same as Flush All
- Clear Cache by URL - same as Flush URL
- Clear Cache by Tag - same as Flush Tags
- Clear Cache by Type - purge all cached HTML, images, or assets in one step, same as Flush Content Class