Guides

Purging Files from the CDN

You can purge files from the CDN by making a POST request to the Purge content endpoint.

Use this guide to learn more about how to use the StackPath API to purge files from the CDN.

Purging a Single File

In the example below, we are purging a single file, /path/to/file, from the site domain.com.

curl --request POST \
     --url https://gateway.stackpath.com/cdn/v1/stacks/STACK_ID/purge \
     --header 'accept: application/json' \
     --header 'authorization: Bearer BEARER_TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
     "items": [
          {
               "url": "//domain.com/path/to/file",
               "recursive":true
          }
     ]
}
'
  • For the protocol, // will purge regardless of protocol, whereas https:// and http:// will only purge assets delivered over that protocol.
  • For the query strings, if Query String Control is set to Cache All Query Strings, then only the asset that matches the URL exactly, including query strings, will be purged. 

To purge all versions of the asset, set the recursive option to true. Review the following example: 

curl --request POST \
     --url https://gateway.stackpath.com/cdn/v1/stacks/STACK_ID/purge \
     --header 'accept: application/json' \
     --header 'authorization: Bearer BEARER_TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
     "items": [
          {
               "url": "//domain.com/path/to/file",
               "recursive":true
          }
     ]
}
'

Purge a Directory Recursively

You can purge a directory recursively the same way you would purge a file recursively, making sure to set the recursive option to true.

curl --request POST \
     --url https://gateway.stackpath.com/cdn/v1/stacks/STACK_ID/purge \
     --header 'accept: application/json' \
     --header 'authorization: Bearer BEARER_TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
     "items": [
          {
               "url": "//domain.com/path/to/directory",
               "recursive":true
          }
     ]
}
'

Purge by Header

The following is an example where we are purging using HEADER as a selectorType, meaning that content will be purged based on an HTTP response header.

curl --request POST \
     --url https://gateway.stackpath.com/cdn/v1/stacks/STACK_ID/purge \
     --header 'accept: application/json' \
     --header 'authorization: Bearer BEARER_TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
     "items": [
          {
               "purgeSelector": [
                    {
                         "selectorType": "HEADER",
                         "selectorName": "(?i)<HEADER_NAME>",
                         "selectorValue": "<HEADER_VALUE>"
                    }
               ],
               "url": "domain.com/path/to/directory",
               "recursive": true
          }
     ]
}
'

In the request body above: (?i) tells the CDN to match the header with case insensitivity.

Additionally, selectorName and selectorValue allow glob-y matching. For example, x-custom-* would match x-custom-header and x-custom-test. This option allows for custom purging solutions. 

Purge all Assets from a Site

See the example below for how to purge all assets recursively. Note the trailing / following domain.com.

curl --request POST \
     --url https://gateway.stackpath.com/cdn/v1/stacks/STACK_ID/purge \
     --header 'accept: application/json' \
     --header 'authorization: Bearer BEARER_TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
     "items": [
          {
               "url": "//domain.com/",
               "recursive": true
          }
     ]
}
'

Learn about Purge Rate Limits

To ensure operational efficiency for all users, StackPath limits the number of purge requests to 100 URIs per account every 60 seconds. Recursive purges count each request, not each file purged.

For example, if you send a single request for a purge of 50 URIs, and then 5 seconds later you send another request for 50 URIs, then both purge calls will execute successfully. 

If you send a purge request that will exceed your purge limit, then none of the purges will take place. 

For example, if you send a request to purge 120 URIs, then none of the URIs will be purged. 

When using the API and you encounter a rate limit, then you will receive a 429 response, which will contain the number of seconds until you can purge again. Review the following example: 

{
   "code": 8,
   "message": "Too many CDN purge requests received. Please retry this request in 56 seconds.",
   "details": [
     {
       "@type": "stackpath.rpc.RetryInfo",
       "retryDelay": "56s"
     },
     {
       "@type": "stackpath.rpc.RequestInfo",
       "requestId": "75529166c9690116",
       "servingData": ""
     }
   ]
}

If you want to raise your purge limit, please contact Support.

Updated 30 days ago