Patch Pools

Apply changes to a number of existing pools, overwriting the supplied properties. Pools are ordered by ascending name. Returns the list of affected pools. Supports the standard pagination query parameters, either limit/offset or per_page/page.

application/json

Body

result

required

Any of

allOf {2}

array[object (pool) {17}]

allOf {2}

One of

array[object (pool) {17}]

object

check_regions

array[string] | null

check_regions

optional

A list of regions from which to run health checks. Null means every Cloudflare data center.

Allowed values:

WNAMENAMWEUEEUNSAMSSAMOCMENAFSAFSASSEASNEASALL_REGIONS

Example:

["WEU","ENAM"]

created_on

string <date-time>

timestamp

read-onlyoptional

Example:

2014-01-01T05:20:00.12345Z

description

string

pool_components-schemas-description

optional

A human-readable description of the pool.

Example:

Primary data center - Provider XYZ

disabled_at

string <date-time>

schemas-disabled_at

read-onlyoptional

This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at.

enabled

boolean

pool_components-schemas-enabled

optional

Whether to enable (the default) or disable this pool. Disabled pools will not receive traffic and are excluded from health checks. Disabling a pool will cause any load balancers using it to failover to the next pool (if any).

Default:

true

Example:

false

pool_components-schemas-identifier

optional

Example:

17b5962d775c646f3f9725cbc7a53df4

latitude

number

latitude

optional

The latitude of the data center containing the origins used in this pool in decimal degrees. If this is set, longitude must also be set.

load_shedding

object

load_shedding

optional

Configures load shedding policies and percentages for the pool.

longitude

number

longitude

optional

The longitude of the data center containing the origins used in this pool in decimal degrees. If this is set, latitude must also be set.

minimum_origins

integer

minimum_origins

optional

The minimum number of origins that must be healthy for this pool to serve traffic. If the number of healthy origins falls below this number, the pool will be marked unhealthy and will failover to the next available pool.

Default:

modified_on

string <date-time>

timestamp

read-onlyoptional

Example:

2014-01-01T05:20:00.12345Z

monitor

schemas-monitor

optional

The ID of the Monitor to use for checking the health of origins within this pool.

name

string

pool_components-schemas-name

optional

A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed.

Example:

primary-dc-1

notification_email

string

notification_email

optional

The email address to send health status notifications to. This can be an individual mailbox or a mailing list. Multiple emails can be supplied as a comma delimited list.

Example:

someone@example.com,sometwo@example.com

notification_filter

object | null

notification_filter

optional

Filter pool and origin health notifications by resource type or health status. Use null to reset.

Example:

{"origin":{"disable":true},"pool":{"healthy":false}}

origin_steering

object

origin_steering

optional

Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity.

origins

array[object (schemas-origin) {6}]

origins

optional

The list of origins within this pool. Traffic directed at this pool is balanced across all currently healthy origins, provided the pool itself is healthy.

errors

array [object {2}]

messages

required

Example:

[]

code

integer

required

>= 1000

message

string

required

messages

array [object {2}]

messages

required

Example:

[]

code

integer

required

>= 1000

message

string

required

success

enum<boolean>

required

Whether the API call was successful

Allowed value:

true

Example:

true

result_info

object

result_info

optional

count

number

optional

Total number of results for the requested service

Example:

page

number

optional

Current page within paginated list of results

Example:

per_page

number

optional

Number of results per page of results

Example:

total_count

number

optional

Total results available without any search parameters

Example:

2000

Example

{
    "errors": [],
    "messages": [],
    "result": [
        {
            "check_regions": [
                "WEU",
                "ENAM"
            ],
            "created_on": "2014-01-01T05:20:00.12345Z",
            "description": "Primary data center - Provider XYZ",
            "disabled_at": "2019-08-24T14:15:22Z",
            "enabled": false,
            "id": "17b5962d775c646f3f9725cbc7a53df4",
            "latitude": 0,
            "load_shedding": {
                "default_percent": 0,
                "default_policy": "random",
                "session_percent": 0,
                "session_policy": "hash"
            },
            "longitude": 0,
            "minimum_origins": 1,
            "modified_on": "2014-01-01T05:20:00.12345Z",
            "monitor": null,
            "name": "primary-dc-1",
            "notification_email": "someone@example.com,sometwo@example.com",
            "notification_filter": {
                "origin": {
                    "disable": true
                },
                "pool": {
                    "healthy": false
                }
            },
            "origin_steering": {
                "policy": "random"
            },
            "origins": [
                {
                    "address": "0.0.0.0",
                    "disabled_at": "2019-08-24T14:15:22Z",
                    "enabled": true,
                    "header": {
                        "Host": "www.example.com"
                    },
                    "name": "app-server-1",
                    "weight": 0.6
                }
            ]
        }
    ],
    "success": true,
    "result_info": {
        "count": 1,
        "page": 1,
        "per_page": 20,
        "total_count": 2000
    }
}

Request

Request samples

Responses