Health checks

A health check belongs to one record value and is keyed by that value’s uuid (record_id) — one check per value. The check runs only while the value’s host_health is Auto; that mode is the check’s on/off switch. See DNS hosting.

interface HealthCheck {
  record_id: string;          // uuid of the record value
  type: 'http' | 'tcp' | 'ping';
  name?: string;              // free-form label
  config: HttpConfig | TcpConfig | PingConfig;
  interval: number;           // seconds between runs
  timeout: number;            // seconds per attempt
  retries?: number;
  retry_interval?: number;    // seconds between attempts
  last_status: 'UNKNOWN' | 'HEALTHY' | 'UNHEALTHY';  // read-only, live
  last_checked_at?: number;   // Unix seconds, read-only; absent while UNKNOWN
  last_error?: string;        // read-only
  created_at: number;
  updated_at: number;
}

last_status is the check’s current result. It is UNKNOWN while the value is not on Auto, and again after every change of the value’s host_health, until the next run.

Check types

type	config
http	url (http or https); optional method (GET, POST, HEAD), expectedStatus (array of accepted codes, e.g. [200, 204]), headers (object), body (string).
tcp	host, port — succeeds when a TCP connection opens.
ping	address — ICMP echo.

Timing

All times are in seconds.

Field	Range
interval	30 – 86 400 (30 seconds – 24 hours) between runs; your package may require more
timeout	1 – 30 per attempt
retries	0 – 5 retries before the value counts as unhealthy
retry_interval	5 – 60 between attempts; 5 when not set

One run, with all its retries, must end before the next one is due:

timeout × (retries + 1) + retry_interval × retries  <  interval

A check that breaks this rule is refused with 422 — on create, and on change against the stored values.

The zone Owner’s package sets the shortest interval allowed (auth.healthchecks.min_interval_s). A faster one is refused with 403 PLAN_LIMIT when you create a check or change its interval; a check that already runs faster keeps running. With timeout 5, retries 3 and retry_interval 5 a run takes at most 35 s, so interval must be at least 36.

List checks of a value

GET /api/v1/health-checks

Query record_id (required): the value’s check as a list of zero or one item. There is no list per zone. An optional zone_id must match the value’s zone, or the list is empty.

Get a check

GET /api/v1/health-checks/:record_id

curl -H "Authorization: Bearer $DINIO_API_KEY" \
  https://api-dinio.bitelex.com/api/v1/health-checks/$VALUE_ID

Create a check

POST /api/v1/health-checks

Field	Type
record_id	uuid	The record value to check: an A, AAAA, SRV or MX value.
type	string	http, tcp or ping. Cannot change later.
config	object	Per type.
interval, timeout	integer	Required, seconds. See Timing.
retries, retry_interval	integer	Optional.
name	string	Optional label, up to 255 characters.

curl -X POST -H "Authorization: Bearer $DINIO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "record_id": "'$VALUE_ID'",
    "type": "http",
    "name": "www health",
    "config": { "url": "https://www.example.com/health", "expectedStatus": [200] },
    "interval": 60,
    "timeout": 5,
    "retries": 3,
    "retry_interval": 5
  }' \
  https://api-dinio.bitelex.com/api/v1/health-checks

Returns 201. Creating a check switches the value’s host_health to Auto, so the check starts running right away; it is UNKNOWN until its first run, and the value counts as healthy until then. 409 if the value already has a check; 422 for a value of another type.

Each check counts against the zone Owner’s auth.healthchecks.max: 403 PLAN_LIMIT at the limit, 403 NO_SUBSCRIPTION without an auth package, and a PLAN_USAGE warning near it.

Change a check

PATCH /api/v1/health-checks/:record_id

Any of name, config, interval, timeout, retries, retry_interval. The type cannot change — remove the check and create a new one instead. To pause or resume the check, change the value’s host_health with Change a value.

config is replaced as a whole, not merged: send the complete config for the check’s type.

curl -X PATCH -H "Authorization: Bearer $DINIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"interval":300}' \
  https://api-dinio.bitelex.com/api/v1/health-checks/$VALUE_ID

Remove a check

DELETE /api/v1/health-checks/:record_id

The value stays. If it was on Auto, its host_health goes back to None; Up and Down stay as they are.

curl -X DELETE -H "Authorization: Bearer $DINIO_API_KEY" \
  https://api-dinio.bitelex.com/api/v1/health-checks/$VALUE_ID