API: Monitoring

The monitor category allows you to add uptime monitoring checks and contacts.

Endpoint: monitor/check-list

{
    "checks": {
        "1261": {
            "check_interval": "60",
            "data": "{"target":"1.2.3.4"}",
            "data_nice": {
                "target": "1.2.3.4"
            },
            "data_summary": "target: 1.2.3.4",
            "delay": "1",
            "enabled": "1",
            "id": "1261",
            "name": "ping-1.2.3.4",
            "status": "online",
            "type": "icmp",
            "type_details": {
                "name": "Ping (ICMP)",
                "params": {
                    "force_ip": {
                        "default": "0",
                        "help": "Force IP version when connecting (assuming a domain name is provided).",
                        "name": "Force IP Version",
                        "required": "",
                        "type": {
                            "0": "Any",
                            "4": "IPv4",
                            "6": "IPv6"
                        }
                    },
                    "packetloss": {
                        "default": "",
                        "help": "Trigger check failure even if only some of the ICMP packets are dropped.",
                        "name": "Trigger on Packet Loss",
                        "required": "",
                        "type": "boolean"
                    },
                    "target": {
                        "name": "Target",
                        "placeholder": "e.g. example.com or 1.2.3.4 or 2602:ffb6::1",
                        "required": "1",
                        "type": "string"
                    }
                },
                "short_name": "Ping"
            }
        }
    }
}

Lists the various check types supported by the system. The output includes the supported parameters for each type, which can be passed to monitor/check-add.

Endpoint: monitor/check-types

{
    "success": "yes",
    "types": {
        "dns": {
            "name": "DNS",
            "params": {
                "expect": {
                    "help": "Substring to look for in the query response.",
                    "name": "Expected Response",
                    "placeholder": "e.g. 1.2.3.4",
                    "required": "",
                    "type": "string"
                },
                "name": {
                    "help": "Name to perform query on.",
                    "name": "Name",
                    "placeholder": "e.g. google.com",
                    "required": "1",
                    "type": "string"
                },
                "server": {
                    "name": "DNS Server",
                    "placeholder": "e.g. 8.8.8.8",
                    "required": "",
                    "type": "string"
                },
                "type": {
                    "default": "A",
                    "help": "DNS record type to query for.",
                    "name": "Type",
                    "required": "1",
                    "type": {
                        "A": "A",
                        "AAAA": "AAAA",
                        "MX": "MX",
                        "NS": "NS",
                        "PTR": "PTR",
                        "SOA": "SOA",
                        "SPF": "SPF",
                        "SRV": "SRV",
                        "TXT": "TXT"
                    }
                }
            },
            "short_name": "DNS"
        },
        ...
    }
}

Response notes:

• If a parameter is required (required='1'), then check-add will fail if that parameter is not set.

Add a new monitoring check. To receive notifications, you'll need to associate this check with contacts: see monitor/contact-add and monitor/alert-add.

Required parameters:

• name - a label for this check
• type - the check type, see monitor/check-types
• check_interval - how often to perform the check in seconds (e.g. 60 to perform the check every minute)
• delay - the number of intervals where the check fails before the check is considered offline and notifications are sent (e.g. 1 or 2); the delay also applies in the opposite direction, when check is offline but the checks are succeeding

Notes:

• Additional parameters, some of which may be required, depend on the type of the check. These parameters are specified by the output of monitor/check-types. These parameters must be prefixed by "param_" in the API request, as in the example below.

Endpoint: monitor/check-add
name=mycheck
type=tcp
check_interval=60
delay=1
param_address=1.2.3.4
param_timeout=10

{
    "check_id": "3751",
    "success": "yes"
}

Required parameters:

• check_id - the check ID.

Endpoint: monitor/check-remove
check_id=3751

{"success": "yes"}

Endpoint: monitor/contact-list

{
    "contacts": {
        "1900": {
            "data": "noreply@example.com",
            "id": "1900",
            "type": "email"
        }
    },
    "success": "yes"
}

Response notes:

• The contacts attribute contains a JSON object where keys are contact IDs and values encode the corresponding contacts.

Add a new contact that can be alerted when a check fails. To associate the contact with a check, see monitor/alert-add.

Required parameters:

• type - one of 'email', 'sms', 'voice', or 'http'
• rel - an e-mail address, phone number, or URL

Endpoint: monitor/contact-add
type=email
rel=noreply@example.com

{"success":"yes"}

Required parameters:

• contact_id - the contact ID.

Endpoint: monitor/contact-remove
contact_id=1900

{"success": "yes"}

Required parameters:

• check_id - the check ID

Endpoint: monitor/alert-list
check_id=3754

{
    "alerts": {
        "3892": {
            "contact": "noreply@example.com",
            "contact_id": "13",
            "id": "3892",
            "type": "both"
        }
    },
    "success": "yes"
}

Create an alert to associate a contact with a check.

Required parameters:

• check_id - the check ID
• contact_id - the contact ID

Endpoint: monitor/alert-add
check_id=3754
contact_id=13

{"success":"yes"}

Required parameters:

• alert_id - the alert ID.

Endpoint: monitor/alert-remove
alert_id=3892

{"success": "yes"}