Invalidate Cached Content by Environment

POST/zones/{zone_id}/environments/{environment_id}/invalidate_cache

Marks cached content as stale for one environment of the zone. Content cached for the zone’s other environments, including production, is not affected. Otherwise this works like POST /zones/{zone_id}/invalidate_cache: the next request for invalidated content makes Cloudflare revalidate it with your origin, and the request body takes the same fields.

Environments are part of Version Management. To delete the content instead, use POST /zones/{zone_id}/environments/{environment_id}/purge_cache.

Invalidating by URL (files) does not work for environments that select requests by IP address, country, ASN, or threat score, and fails with error 1136. Use tags, hosts, prefixes, or purge_everything for those environments.

Availability and limits

Rate limits and the number of items you can send in one request depend on your plan. See Purge cache: availability and limits.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Accepted Permissions (at least one required)

Zone Versioning Write

Path ParametersExpand Collapse

zone_id: string

maxLength32

environment_id: string

maxLength32

Body ParametersJSONExpand Collapse

body: object { tags } or object { hosts } or object { prefixes } or 3 more

One of the following:

CachePurgeFlexPurgeByTags object { tags }

tags: optional array of string

Cache tags. Targets all content whose Cache-Tag response header contains at least one of these tags. See Purge cache by cache-tags.

CachePurgeFlexPurgeByHostnames object { hosts }

hosts: optional array of string

Hostnames, such as www.example.com. Targets all content cached for these hostnames. See Purge cache by hostname.

CachePurgeFlexPurgeByPrefixes object { prefixes }

prefixes: optional array of string

URL prefixes, each a hostname followed by a path, such as www.example.com/blog/. Targets all content whose URL starts with one of these prefixes. Do not include a scheme, query string, or fragment. See Purge cache by prefix.

CachePurgeEverything object { purge_everything }

purge_everything: optional boolean

Set to true to target all cached content in the zone, or in the environment for the environment endpoints. Must be the only field in the request. See Purge everything.

CachePurgeSingleFile object { files }

files: optional array of string

Full URLs, such as https://www.example.com/css/styles.css. Targets the content cached for each URL. If your cache key includes request headers, send objects with url and headers instead. See Purge by single-file.

CachePurgeSingleFileWithURLAndHeaders object { files }

files: optional array of object { headers, url }

URLs with the request headers your cache key uses. Use this form when your cache key includes request headers, or the visitor’s device type, country, or language: send the header values each URL was cached with, such as CF-Device-Type, CF-IPCountry, or Accept-Language.

When you send the Origin header, include the scheme and hostname. Include the port unless it is the default for the scheme: 80 for http, 443 for https.

See Purge by single-file.

headers: optional map[string]

Request headers and the values the content was cached with.

url: optional string

Full URL of the content.

ReturnsExpand Collapse

errors: array of ResponseInfo { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

messages: array of ResponseInfo { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

success: boolean

Indicates the API call’s success or failure.

result: optional object { id }

id: string

maxLength32

Invalidate Cached Content by Environment

curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/environments/$ENVIRONMENT_ID/invalidate_cache \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "tags": [
            "product-1234",
            "homepage"
          ]
        }'

{
  "errors": [],
  "messages": [],
  "result": {
    "id": "023e105f4ecef8ad9ca31a8372d0c353"
  },
  "success": true
}

{
  "errors": [
    {
      "code": 1092,
      "message": "Request cannot contain \"purge_everything\" and any of \"files\", \"tags\", \"hosts\" or \"prefixes\""
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}

{
  "errors": [
    {
      "code": 1134,
      "message": "Unable to purge, rate limit reached. Please wait and consider throttling your request speed"
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}

Returns Examples

{
  "errors": [],
  "messages": [],
  "result": {
    "id": "023e105f4ecef8ad9ca31a8372d0c353"
  },
  "success": true
}

{
  "errors": [
    {
      "code": 1092,
      "message": "Request cannot contain \"purge_everything\" and any of \"files\", \"tags\", \"hosts\" or \"prefixes\""
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}

{
  "errors": [
    {
      "code": 1134,
      "message": "Unable to purge, rate limit reached. Please wait and consider throttling your request speed"
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}