CubePathDOCS

DNS Zones

Set record health check

put/dns/zones/{zone_uuid}/records/{record_uuid}/health-check

Add or update the health check on a DNS record. When the target stops responding, the record is automatically removed from DNS answers until it recovers. If every server of a name fails it still answers with all of them, unless strict is on. Billed at $10/month per health check.

Autorización

Authorization
Authorization*string

Bearer YOUR_API_TOKEN con un token de API. También vale la cabecera X-API-Key: YOUR_API_TOKEN.

Parámetros de ruta

zone_uuid*string
record_uuid*string

Cuerpo de la petición

Create or update the health check attached to a DNS record (1 per record).

application/jsonObligatorio
name*string

Friendly name

Rangolength ≤ 128
check_type*DNSHealthCheckType
Valores"http""https""tcp""ping"
target?string | null

Host/IP to probe; defaults to the record's own value

Rangolength ≤ 255
port?integer | null

Port (required for TCP)

Rango1 ≤ value ≤ 65535
path?string | null

Path for HTTP/HTTPS checks

Rangolength ≤ 255
expected_status?integer | null

Expected HTTP status code

Rango100 ≤ value ≤ 599Por defecto200
interval_secs?integer

Seconds between checks (min 10)

Rango10 ≤ value ≤ 3600Por defecto60
timeout_secs?integer

Per-check timeout in seconds

Rango1 ≤ value ≤ 60Por defecto5
healthy_threshold?integer

Successes before marking healthy

Rango1 ≤ value ≤ 10Por defecto2
unhealthy_threshold?integer

Failures before marking unhealthy

Rango1 ≤ value ≤ 10Por defecto3
enabled?boolean

Whether the check is active (billed while enabled)

Por defectotrue
strict?boolean

If every server fails, do not answer. Off (default): when all the records of a name are unhealthy, DNS still answers with all of them. On: only healthy records are ever served, so the name gets an empty answer while none is healthy

Por defectofalse

Respuestas

Successful Response

application/json

uuid*string
record_uuid*string
name*string
check_type*DNSHealthCheckType
Valores"http""https""tcp""ping"
target?string | null
port?integer | null
path?string | null
expected_status?integer | null
interval_secs*integer
timeout_secs*integer
healthy_threshold*integer
unhealthy_threshold*integer
enabled*boolean
strict?boolean

If every server fails, do not answer: only healthy records are served (see the PUT).

Por defectofalse
last_status*DNSHealthCheckStatus
Valores"healthy""unhealthy""unknown"
last_check_at?string | null
Formatodate-time
created_at*string
Formatodate-time
updated_at*string
Formatodate-time
status_summary?DNSHealthCheckStatusSummary | null

Current status combined across every location; null while unavailable.

Propiedades (3)
status*string

healthy: every reporting location sees the target up; unhealthy: every one sees it down; degraded: some locations see it down; unknown: no location is reporting yet; paused: the check is disabled or the zone is not active.

Valores"healthy""degraded""unhealthy""unknown""paused"
pops?array<DNSHealthCheckPopStatus>
Propiedades (2)
pop*string

Location code, e.g. ams01

status*string

unhealthy when the location sees the target down, unknown while it is not reporting yet.

Valores"healthy""unhealthy""unknown""paused"
last_change_at?string | null

Last status change seen by any location (ISO 8601 UTC)

uptime_24h?number | null

Percentage of the last 24 hours the target was seen up; null without data.