Skip to content
WP EngineDocumentation

Replace the cache exclusions for a WordPress installation

PUT
/installs/{install_id}/cache_exclusions
curl --request PUT \
  --url https://api.wpengineapi.com/v1/installs/294deacc-d8b8-4005-82c4-0727ba8ddde0/cache_exclusions \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '{ "exclusions": [ { "type": "url path", "value": "/foo" }, { "type": "query arg", "value": "utm_source" } ] }'

Replaces the full set of cache exclusion rules for an install with the list supplied in the request body, and returns the resulting list.

Behavior
  • This is a full replacement, not a partial update: any exclusion currently configured but absent from exclusions is removed, and an empty array clears every writable exclusion
  • Duplicate entries are collapsed before being saved
  • Entries of type cookie are managed by the platform and cannot be written here. They are accepted and ignored, so a list read from GET /installs/{install_id}/cache_exclusions can be edited and sent back unchanged, and they continue to appear in the response. To add or change one, see Exclude pages from cache when a cookie is present
  • Each value is matched as a regular expression; an invalid expression returns a 400
  • Requires an eligible account and a user who can update the install; otherwise returns a 403
  • Exclusions cannot be modified while the install is transferable; such requests return a 409 and leave the existing exclusions unchanged. Reading them with GET /installs/{install_id}/cache_exclusions is still permitted

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
install_id
required
string format: uuid

ID of install

Example
294deacc-d8b8-4005-82c4-0727ba8ddde0

Request Bodyrequired

Section titled “Request Bodyrequired”
Properties
  • exclusions - required - The complete list of cache exclusions for the install. Each entry requires a type (query arg, url path, or cookie) and a value. Entries of type cookie are ignored when saving
Media typeapplication/json
object
exclusions
required

The complete set of cache exclusions to apply to the install

Array<object>
object
type
required

The kind of request attribute this exclusion matches on

string
Allowed values: query arg url path cookie
Example
url path
value
required

The value used to match requests that should bypass the cache

string
Example
/foo
Example
{
  "exclusions": [
    {
      "type": "url path",
      "value": "/foo"
    },
    {
      "type": "query arg",
      "value": "utm_source"
    }
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

The resulting cache exclusions for the install

Media typeapplication/json
object
results
Array<object>
object
type
required

The kind of request attribute this exclusion matches on

string
Allowed values: query arg url path cookie
value
required

The value used to match requests that should bypass the cache

string
Example
{
  "results": [
    {
      "type": "query arg",
      "value": "/foo"
    }
  ]
}

400

Section titled “400”

Bad Request

Media typeapplication/json
object
message
required

A message regarding the error that occurred on the server

string
documentation_url

(Optional) A URL where documentation regarding this specific error can be found

string
errors

An array of error objects describing specific errors that arose when servicing the request

Array<object>
object
resource
required

The name of the resource that was being processed when the error occurred

string
field
required

(Optional) The specific field associated with the error

string
type
required

(Optional) A type associated with the error. invalid_value, access_error, value_unavailable

string
code
required

(Optional) A machine code relating to the error that occurred with the field and resource

string
message
required

(Optional) A human-readable message relating to the error that occurred with the field and resource

string
Example
{
  "message": "Invalid Site: Name cannot be empty.",
  "errors": [
    {
      "resource": "Site",
      "field": "name",
      "type": "invalid_value",
      "code": "too_long",
      "message": "Name is too long (maximum is 40 characters)"
    }
  ]
}

401

Section titled “401”

Authentication Error

Media typeapplication/json
object
message
required

A message regarding the error that occurred on the server

string
documentation_url

(Optional) A URL where documentation regarding this specific error can be found

string
Example
{
  "message": "Bad Credentials"
}

403

Section titled “403”

Not authorized

Media typeapplication/json
object
message
required

A message regarding the error that occurred on the server

string
documentation_url

(Optional) A URL where documentation regarding this specific error can be found

string
Example
{
  "message": "You don't have permission to perform that action"
}

404

Section titled “404”

Not found

Media typeapplication/json
object
message
required

A message regarding the error that occurred on the server

string
documentation_url

(Optional) A URL where documentation regarding this specific error can be found

string
Example
{
  "message": "Not Found"
}

409

Section titled “409”

Conflict — cache exclusions cannot be modified while the install is transferable

Media typeapplication/json
object
message
required

A message regarding the conflict that occurred

string
documentation_url

(Optional) A URL where documentation regarding this specific error can be found

string
errors

An array of error objects describing specific errors that arose when servicing the request

Array<object>
object
resource
required

The name of the resource that was being processed when the error occurred

string
field
required

(Optional) The specific field associated with the error

string
type
required

(Optional) A type associated with the error. invalid_value, access_error, value_unavailable

string
code
required

(Optional) A machine code relating to the error that occurred with the field and resource

string
message
required

(Optional) A human-readable message relating to the error that occurred with the field and resource

string
Example
{
  "message": "Transfer has already started and cannot be cancelled",
  "errors": [
    {
      "resource": "Site",
      "field": "name",
      "type": "invalid_value",
      "code": "too_long",
      "message": "Name is too long (maximum is 40 characters)"
    }
  ]
}

429

Section titled “429”

Too many requests

500

Section titled “500”

Internal server error

Media typeapplication/json
object
message
required

A message regarding the error that occurred on the server

string
Example
{
  "message": "An unexpected error occurred, please try again in a few minutes"
}

503

Section titled “503”

Service unavailable