---
url: https://docs.smoxy.eu/developer-guide/cache-invalidation.md
---
# 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](/zones/cache#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](/developer-guide/cloudflare-setup) for the recommended workaround.
:::

***

### Methods

#### Flush URL

Clears the cache for a specific URL.

```bash
curl -X BAN -H "secret: <token>" -H "url: /" https://www.example.com/
```

You can also pass the URL as the request target:

```bash
curl -X BAN -H "secret: <token>" https://www.example.com/products/my-product
```

#### Flush 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:

```bash
curl -X BAN -H "secret: <token>" -H "tags: smartphones" https://www.example.com/
```

Flush multiple tags at once (comma-separated):

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

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

```bash
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](#quick-actions) in the Hub, or over the [Hub API](/api/) by sending `POST /api/zones/{zoneId}/cache/clear` with `action` set to `html`, `images`, or `assets`:

```bash
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](#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.

```bash
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](#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
