Create Preview Health Check

Create a new preview health check.

Request

Path Params

zone_identifier

string

required

Body Params application/json

address

string

required

The hostname or IP address of the origin server to run health checks on.

Example:

www.example.com

check_regions

array[string] | null

optional

A list of regions from which to run health checks. Null means Cloudflare will pick a default region.

Allowed values:

WNAMENAMWEUEEUNSAMSSAMOCMENAFSAFINSEASNEASALL_REGIONS

Example:

["WEU","ENAM"]

consecutive_fails

integer

optional

The number of consecutive fails required from a health check before changing the health to unhealthy.

Default:

consecutive_successes

integer

optional

The number of consecutive successes required from a health check before changing the health to healthy.

Default:

description

string

optional

A human-readable description of the health check.

Example:

Health check for www.example.com

http_config

object (http_config) | null

optional

Parameters specific to an HTTP or HTTPS health check.

allow_insecure

boolean

optional

Do not validate the certificate when the health check uses HTTPS.

Default:

false

expected_body

string

optional

A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy.

Example:

success

expected_codes

array[string] | null

optional

The expected HTTP response codes (e.g. "200") or code ranges (e.g. "2xx" for all codes starting with 2) of the health check.

Default:

200

Example:

["2xx","302"]

follow_redirects

boolean

optional

Follow redirects if the origin returns a 3xx status code.

Default:

false

header

object | null

optional

The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden.

Example:

{"Host":["example.com"],"X-App-ID":["abc123"]}

method

enum<string>

optional

The HTTP method to use for the health check.

Allowed values:

GETHEAD

Default:

GET

path

string

optional

The endpoint path to health check against.

Default:

Example:

/health

port

integer

optional

Port number to connect to for the health check. Defaults to 80 if type is HTTP or 443 if type is HTTPS.

Default:

interval

integer

optional

The interval between each health check. Shorter intervals may give quicker notifications if the origin status changes, but will increase load on the origin as we check from multiple locations.

Default:

name

string

required

A short name to identify the health check. Only alphanumeric characters, hyphens and underscores are allowed.

Example:

server-1

retries

integer

optional

The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately.

Default:

suspended

boolean

optional

If suspended, no health checks are sent to the origin.

Default:

false

tcp_config

object (tcp_config) | null

optional

Parameters specific to TCP health check.

method

enum<string>

optional

The TCP connection method to use for the health check.

Allowed value:

connection_established

Default:

connection_established

port

integer

optional

Port number to connect to for the health check. Defaults to 80.

Default:

timeout

integer

optional

The timeout (in seconds) before marking the health check as failed.

Default:

type

string

optional

The protocol to use for the health check. Currently supported protocols are 'HTTP', 'HTTPS' and 'TCP'.

Default:

HTTP

Example:

HTTPS

Example

{
    "address": "www.example.com",
    "check_regions": [
        "WEU",
        "ENAM"
    ],
    "consecutive_fails": 1,
    "consecutive_successes": 1,
    "description": "Health check for www.example.com",
    "http_config": {
        "allow_insecure": false,
        "expected_body": "success",
        "expected_codes": [
            "2xx",
            "302"
        ],
        "follow_redirects": false,
        "header": {
            "Host": [
                "example.com"
            ],
            "X-App-ID": [
                "abc123"
            ]
        },
        "method": "GET",
        "path": "/health",
        "port": 80
    },
    "interval": 60,
    "name": "server-1",
    "retries": 2,
    "suspended": false,
    "tcp_config": {
        "method": "connection_established",
        "port": 80
    },
    "timeout": 5,
    "type": "HTTPS"
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Create Preview Health Check response

application/json

Body

allOf {2}

optional

object (api-response-single)

optional

errors

array [object {2}]

messages

required

Example:

[]

messages

array [object {2}]

messages

required

Example:

[]

result

required

success

enum<boolean>

required

Whether the API call was successful

Allowed value:

true

Example:

true

object

optional

result

object (healthchecks)

optional

Example

{
    "errors": [],
    "messages": [],
    "result": {
        "address": "www.example.com",
        "check_regions": [
            "WEU",
            "ENAM"
        ],
        "consecutive_fails": 1,
        "consecutive_successes": 1,
        "created_on": "2014-01-01T05:20:00.12345Z",
        "description": "Health check for www.example.com",
        "failure_reason": "",
        "http_config": {
            "allow_insecure": false,
            "expected_body": "success",
            "expected_codes": [
                "2xx",
                "302"
            ],
            "follow_redirects": false,
            "header": {
                "Host": [
                    "example.com"
                ],
                "X-App-ID": [
                    "abc123"
                ]
            },
            "method": "GET",
            "path": "/health",
            "port": 80
        },
        "id": "699d98642c564d2e855e9661899b7252",
        "interval": 60,
        "modified_on": "2014-01-01T05:20:00.12345Z",
        "name": "server-1",
        "retries": 2,
        "status": "healthy",
        "suspended": false,
        "tcp_config": {
            "method": "connection_established",
            "port": 80
        },
        "timeout": 5,
        "type": "HTTPS"
    },
    "success": true
}

🟢200Create Preview Health Check response failure