# How to Manage the Spaces CDN Cache

Spaces Object Storage is an S3-compatible service for storing and serving large amounts of data. The built-in Spaces CDN minimizes page load times, improves performance, and reduces bandwidth and infrastructure costs.

After you [enable the Spaces CDN](https://docs.digitalocean.com/products/spaces/how-to/enable-cdn/index.html.md), the CDN’s edge servers begin caching and serving the contents of the Spaces bucket.

**Note**: Spaces Cold Storage buckets do not support CDN integration or custom CDN endpoints. To use CDN caching or custom subdomains, create a Spaces Standard Storage bucket instead. For more information, see [Spaces Limits](https://docs.digitalocean.com/products/spaces/details/limits/index.html.md).

Using presigned URLs does not allow transferred files to be cached when using the Spaces CDN. Attempting to do so may result in double the bandwidth charge without the CDN’s performance benefit.

Each request with a unique URL, including the URL’s query string, is treated as a unique asset and has its own cache. Requests with identical URLs return the same cached value. For example, the caches for the following two URLs are separate because the query strings are different:

```text
nyc3.cdn.digitaloceanspaces.com/examplefile.jpg?query=examplequery
nyc3.cdn.digitaloceanspaces.com/examplefile.jpg?query=differentquery
```

This URL is based on the datacenter you created your bucket in, followed by `digitaloceanspaces.com`. For nyc3, for example, use `nyc3.digitaloceanspaces.com/...`.

There are two ways you can control the CDN cache:

- [**Set the edge cache TTL**](#ttl). The edge cache TTL determines how long the CDN’s edge servers keep a particular copy of your files before getting the current version from the origin.
- [**Purge the cache**](#purge). Purging files from the CDN cache makes all edge servers immediately clear their versions of those files and request the current version from buckets.

  You may want to purge files to quickly correct errors, fully remove deleted content, or deploy urgent fixes.

## Set the Edge Cache TTL Using the Control Panel

You can set the default edge cache TTL for the entire bucket and customize the TTL for specific files.

### Change the Bucket’s Default Edge Cache TTL

The edge cache TTL for Spaces is set to one hour by default. You can change this when you first enable the CDN and modify it at any time after.

To change the bucket’s default edge cache TTL, go to the [control panel](https://cloud.digitalocean.com/), in the left menu, click **Spaces Object Storage**, and then under the **Buckets** tab, click the bucket you want to change the edge cache TTL for. From the bucket’s overview page, click the **Settings** tab, under the **CDN (content Delivery Network)** section, click **Edit**, and then in the **Edge Cache TTL** sub-section, click the drop-down menu, and then choose a new time.

A longer TTL improves performance, but you can’t see updated content until the cached version expires. Use longer TTLs for static content or content that rarely changes, and shorter TTLs for dynamic or frequently updated content. You may also want to increase the edge cache TTL if you expect a significant spike in traffic.

After setting the new time for your edge cache TTL, click **Save**.

### Customize the Edge Cache TTL for Specific Files

If you want the edge cache TTL for specific files to differ from the default of the bucket, you can [add a custom key-value pair to the file’s metadata](https://docs.digitalocean.com/products/spaces/how-to/set-file-metadata/index.html.md).

To customize the edge cache TTL for specific files, go to the [control panel](https://cloud.digitalocean.com/), in the left menu, click **Spaces Object Storage**, and then under the **Buckets** tab, click the bucket you want to change edge cache TTL for specific files.

From the bucket’s overview page, under the **Files** tab, either click the file you want to manage edge cache TTL for or on the left, click the checkbox to select multiple files, and then on the right, click **…**, click **Manage Metadata** to open the **Manage metadata** window for the specific file.

In this window, at the bottom, click **Add Custom Pairing**, and then enter `max-age` as the **Key**, which specifies how long, in seconds, the file can be cached by CDN edge servers before it must be revalidated. Then, as the **Value**, enter the TTL you want in seconds, and then click **Save**.

## Set the Edge Cache TTL Using Automation

The DigitalOcean CLI (`doctl`) does not support configuring edge cache TTL settings for Spaces buckets. To manage edge cache behavior, [use the API](#set-the-edge-cache-ttl-via-the-api).

### Set the Edge Cache TTL via the API

You can set the default edge cache TTL for a bucket by updating the bucket’s CDN configuration. The TTL value is specified in seconds and applies to all cached objects unless overridden by a custom rule.

To update the edge cache TTL, send a PUT request to the CDN configuration endpoint for your bucket. Ensure the request is authenticated and sent to the correct region endpoint.

## How to Using the DigitalOcean API

1. [Create a personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) and save it for use with the API.
2. Send a PUT request to [`https://api.digitalocean.com/v2/spaces/buckets/{bucket_name}/cdn`](https://docs.digitalocean.com/reference/api/digitalocean//index.html.md#operation/%25!s%28%3Cnil%3E%29).

You can also customize the edge cache TTL for specific files by defining cache rules that match object paths or file extensions. These rules allow you to override the default TTL for selected content, such as frequently updated files or long-lived static assets.

To add or update cache rules, include them in the same CDN configuration request when updating the bucket. Rules are evaluated in order and applied to matching objects.

## How to Using the DigitalOcean API

1. [Create a personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) and save it for use with the API.
2. Send a PUT request to [`https://api.digitalocean.com/v2/spaces/buckets/{bucket_name}/cdn`](https://docs.digitalocean.com/reference/api/digitalocean//index.html.md#operation/%25!s%28%3Cnil%3E%29).

## Purge Files From the CDN Cache

You can purge individual files, recursively purge folders, or purge the entire contents of a bucket using the same method. Purging clears the file(s) or directories from all of your edge caches and requests a pristine copy from Spaces.

To purge files from the CDN cache of your bucket, go to the [control panel](https://cloud.digitalocean.com/), in the left menu, click **Spaces Object Storage**, and then under the **Buckets** tab, click the bucket you want to purge the CDN cache for. From the bucket’s overview page, click the **Settings** tab, and then under the **CDN (content Delivery Network)** section, click **Edit**, and then on the right, click **Change**, and then **Purge CDN Cache** to open the **Purge CDN Cache** window.

To confirm purge, select the directories or the entire bucket to purge the cache for, and then click **Purge Cache in Selected Directories**.

### Purge a Specific File from the CDN Cache

To purge a specific file from the CDN cache, go to the [control panel](https://cloud.digitalocean.com/), in the left menu, click **Spaces Object Storage**, and then under the **Buckets** tab, click the bucket you want to purge a file from the CDN cache. From the bucket’s overview page, under the **Files** tab, find the file you want to purge from the CDN cache, on the right, click **…**, and then click **Purge from CDN cache** to open the **Purge from CDN Cache** window.

To confirm the file’s purge, click **Purge file from CDN Cache**.

### Purge Multiple Files from the CDN Cache

To purge multiple files from the CDN cache, go to the [control panel](https://cloud.digitalocean.com/), in the left menu, click **Spaces Object Storage**, and then under the **Buckets** tab, click the bucket you want to purge files from the CDN cache. From the bucket’s overview page, under the **Files** tab, on the left, click the checkbox for all the files you want to purge, and then in the top right, click **Actions**, and then click **Purge From CDN Cache** to open the **Purge from CDN Cache** window.

To confirm the files purge, click **Purge file from CDN Cache**.

## Purge Files From the CDN Cache Using Automation

You can purge cached content from the Spaces CDN using either the DigitalOcean CLI (`doctl`) or the DigitalOcean API. Purging removes cached objects from edge servers so the next request fetches a fresh copy from the origin bucket.

### Purge Files via the CLI

You can purge the Spaces CDN cache using `doctl`. To purge cached files, use `doctl compute cdn flush` and specify one or more paths (or a wildcard). If you provide only a wildcard (`*`) or no files, all cached content is purged.

## How to Flush the Cache of a CDN Using the DigitalOcean CLI

1. [Install `doctl`](https://docs.digitalocean.com/reference/doctl/how-to/install/index.html.md), the official DigitalOcean CLI.
2. [Create a personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) and save it for use with `doctl`.
3. Use the token to grant `doctl` access to your DigitalOcean account.

   ```shell
   doctl auth init
   ```
4. Finally, run `doctl compute cdn flush`. Basic usage looks like this, but you can [read the usage docs](https://docs.digitalocean.com/reference/doctl/reference/compute/cdn/flush/index.html.md) for more details:

   ```shell
   doctl compute cdn flush <cdn-id> [flags]
   ```

   The following example flushes the cache of the `/path/to/assets` directory in a CDN:

   ```shell
   doctl compute cdn flush 418b7972-fc67-41ea-ab4b-6f9477c4f7d8 --files /path/to/assets/*
   ```

To purge a specific file, provide the file path relative to the bucket. For example, `--files /path/to/file.jpg`.

To purge multiple files, provide multiple `--files` values. For example, `--files /a.jpg --files /b.css --files /dir/c.js`.

To purge all files, use a wildcard or omit the flag. For example, `--files "*"`, or run the command without `--files`.

### Purge Files via the API

To purge cached content from a CDN endpoint, send a DELETE request to the CDN cache endpoint and include a `files` array in the request body. Each entry can be a single file path or include a wildcard (`*`) to purge recursively under a prefix. Providing only `*` purges all cached content.

## How to Purge the Cache for an Existing CDN Endpoint Using the DigitalOcean API

1. [Create a personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) and save it for use with the API.
2. Send a DELETE request to [`https://api.digitalocean.com/v2/cdn/endpoints/{cdn_id}/cache`](https://docs.digitalocean.com/reference/api/digitalocean//index.html.md#operation/cdn_purge_cache).

### cURL

Using cURL:

```shell
curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"files": ["assets/img/hero.png","assets/css/*"]}' \
  "https://api.digitalocean.com/v2/cdn/endpoints/19f06b6a-3ace-4315-b086-499a0e521b76/cache"
```

### Go

Using [Godo](https://github.com/digitalocean/godo), the official DigitalOcean API client for Go:

```go
import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    flushRequest := &godo.CDNFlushCacheRequest{
        Files: []string{"assets/img/hero.png","assets/css/*"},
    }

    _, err := client.CDNs.FlushCache(ctx, "19f06b6a-3ace-4315-b086-499a0e521b76", flushRequest)
}
```

### Ruby

Using [DropletKit](https://github.com/digitalocean/droplet_kit), the official DigitalOcean API client for Ruby:

```ruby
require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

client.cdns.flush_cache(
  id: '19f06b6a-3ace-4315-b086-499a0e521b76',
  files: ['assets/img/hero.png','assets/css/*']
)
```

### Python

Using [PyDo](https://github.com/digitalocean/pydo), the official DigitalOcean API client for Python:

```python
import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

purge_req = {"files": ["path/to/image.png", "path/to/css/*"]}

purge_resp = client.cdn.purge_cache("19f06b6a", purge_req)
```

To purge a specific file, include a single path in `files`. For example, `files: ["/path/to/file.jpg"]`.

To purge multiple files, include multiple paths in `files`. For example, `files: ["/a.jpg", "/b.css", "/dir/c.js"]`.

To purge all files, use a wildcard as the only entry. For example, `files: ["*"]`. The API has a purge rate limit. For more information, see our [limits page](https://docs.digitalocean.com/products/spaces/details/limits/index.html.md).