Documentation

API Reference :: checks

GET
POST & PUT
DELETE
Disable

GET

Get check information - returns check information or a list of checks.

customerid - optional - customerid of the subaccount you want to get a check or list of checks for. If omitted checks for the primary account are returned.
id - optional - Check id of the check you want to get. You can specify a list of checks by separating them with a comma, or setting this parameter to a JSON array of IDs. If absent, the call will return all checks for the account.
lastresult - optional - If this parameter is present the check's last result will be inserted into the response.
current - optional - only valid if retrieving a list of checks. If this parameter is present the checks current events ("down" or "disabled") will be inserted in the response. If you only need to know if the check is passing or not, please do not use the 'current' flag as the "state" element on each check will indicate pass/fail and your API call will be more performant without this flag. Note that the "lastresult" is slightly different from the "current" information. The last result will show the last result, just like a results call with the limit set to 1, regardless of the current state of the check and regardless of when it was (typically up to a month or so ago), as long as there is at least one result for this check. The current event will show if the current state of the check is down or disabled. See the documentation and examples for the results and current calls for more information.
uptime - optional - If this parameter is present the check's uptime will be added to the response. If uptime is included, you can also use the interval, start, end and offset parameters as documented for the UPTIME call.

Request example:

curl -X GET 'https://api.nodeping.com/api/1/checks/201205050153W2Q4C-0J2HSIRF'

Response example:

{
  "_id": "201205050153W2Q4C-0J2HSIRF",
  "_rev": "37-8776f919267df3973fdb33cba0a8dd09",
  "customer_id": "201205050153W2Q4C",
  "label": "Site 1",
  "interval": 1,
  "notifications": [],
  "type": "HTTP",
  "status": "assigned",
  "modified": 1336759793520,
  "enable": "active",
  "public": false,
  "parameters": {
    "target": "http://www.example.com/",
    "threshold": "5",
    "sens": "2"
  },
  "created": 1336185808566,
  "queue": "bINPckIRdv",
  "uuid": "4pybhg6m-4v1y-4enn-8tz5-tvywydu6h04k",
  "state": 0,
  "firstdown": 1336185868566
}

Note that "state" is a boolean that indicates if the check is passing or not (1 means the check is passing, 0 means it's failing) and "firstdown" will be either false for a passing check or a Unix timestamp in milliseconds indicating when the check began to fail.

Additional Request examples:

curl -X GET 'https://api.nodeping.com/api/1/checks/201205050153W2Q4C-0J2HSIRF,201205050153W2Q4C-4RZT8MLN'

curl -X GET 'https://api.nodeping.com/api/1/checks?id=\["201205050153W2Q4C-0J2HSIRF","201205050153W2Q4C-4RZT8MLN"\]&uptime=true&start=2020-06-01'

POST and PUT

Create (POST) or update (PUT) a check - returns information about the check created or modified

id - required string on update - the check id you want to modify. Ignored for POST calls.
customerid - required when creating or updating a check on a subaccount - customerid of the subaccount the check belongs to.
type - required - string check type, one of: AGENT, AUDIO, CLUSTER, DOHDOT, DNS, FTP, HTTP, HTTPCONTENT, HTTPPARSE, HTTPADV, IMAP4, MONGODB, MTR, MYSQL, NTP, PGSQL, PING, POP3, PORT, PUSH, RBL, RDP, REDIS, SIP, SMTP, SNMP, SPEC10DNS, SPEC10RDDS, SSH, SSL, WEBSOCKET, WHOIS
target - required on create (except for AGENT, DNS, PUSH, SPEC10DNS, and SPEC10RDDS type checks), optional on update - string URL or FQDN. The check target. Note that for HTTP, HTTPCONTENT, HTTPPARSE, and HTTPADV checks this must begin with "http://" or "https://".
label - optional string - give this check a label. If this is absent, the target will be used as the label.
interval - optional positive integer or 0.5 or 0.25, defaults to 15 - How often this check runs in minutes. Can be any integer starting at 1 for one minute checks. Once a day is 1440. Sub-minute intervals (30 seconds and 15 seconds) are represented by 0.5 and 0.25 respectively. Additional fees may apply for sub-minute intervals. See your billing page for more info.
enabled - optional string, 'true' or 'false' defaults to 'false'. Set to 'true' or 'active' to enable this check to run.
public - optional string, 'true' or 'false' defaults to 'false'. Set to 'true' to enable public reports for this check.
autodiag - optional string, 'true' or 'false' defaults to 'false'. Set to 'true' to enable automated diagnostics for the check.
runlocations - optional string or json array - This is a geographical region or list of probes where check will run. You can set this to a string of one of the regions: 'nam' for North America, 'lam' for Latin America, 'eur' for Europe, 'eao' for East Asia/Oceania, or 'wlw' for worldwide. You can also set it to an array of two-character probe indicators listed in our FAQ. Example: ["ld","ca","au"]. If omitted, the account's default region setting is used. To run checks on an AGENT, set the location to the ID of the agent check you want to run on.
homeloc - optional string or boolean false (available only with Premiere plan) - Set the preferred probe location, home location, for this check. The default is false and will run the check on a random probe in the selected region (see runlocations) or the account default region if no region is specified on the check. The probe two letter indicators are listed in our FAQ (example: 'ca' would run a check from our California probe). Set this value to 'roam' to have the check change probe location on each interval.
threshold - optional positive integer - the timeout for this check in seconds, defaults to 5 for a five second timeout. Can be any integer starting at 1. For CLUSTER checks, this indicates how many checks listed in the 'data' element must be passing in order for this check to pass. For MTR checks, this is the maxium percentage of packet loss.
sens - optional positive integer - number of rechecks before this check is considered 'down' or 'up'. Defaults to 2 (2 rechecks means it will be checked by 3 different servers). Rechecks are run immediately, not based on the interval and happen when a status change occurs.
notifications - optional json array - array of objects containing the contact id, delay, and scheduling for notifications. The IDs can be obtained by listing the relevant contacts. The format for the data is:
```
[
  {"contactkey1":
    {"delay":0,
     "schedule":"schedule1"
    }
  },
  {"contactkey2":
    {"delay":5,
     "schedule":"schedule2"
    }
  }
]
```
See the Request example below. In order to remove an address from a check's notifications, set the contact key value to "None", so removing notifications to contactkey1 and adding it to contactkey2 would like this: [{"contactkey1":"None"},{"contactkey2":{"delay":0,"schedule":"schedule1"}}]
dep - optional string - the id of the check used for the notification dependency. If the check this is set to is failing, no notifications will be sent. For example, set this to the check id of a PING check on an edge router for all services that depend on that router. It helps reduce the number of alerts you receive when core networks or services go offline. To remove this functionality, set this to false.
mute - optional boolean or millisecond timestamp - default is false. Set to true to mute all notifications for this check. Set to a millisecond timestamp (UTC) in the future to mute all notifications and have it automatically unmuted at that time.
description - optional string - you can put arbitrary text, JSON, XML, etc. Size limit is 1000 characters.
tags - optional array - Array of strings for tags used to group checks in the UI.

The following are only relevant for certain types:

checktoken - read-only field on AGENT and PUSH checks - can request server-side re-generation by setting this field to 'reset'.
clientcert - optional string to specify the ID of a client certificate/key to be used in HTTPADV and DOHDOT checks.
contentstring - optional string for DOHDOT, DNS, HTTPCONTENT, HTTPADV, FTP, SSH, WEBSOCKET, WHOIS type checks - the string to match the response against.
dohdot - string used to specify DoH or DoT in the DOHDOT check. Valid value is either 'doh' or 'dot' - defaults to 'doh'.
dnssection - optional case-sensitive string for which section of the DNS reply to look in for the 'contentstring' match. Valid values are: 'answer', 'authority', 'additional', 'edns_options'. Defaults to 'answer'.
dnstype - optional string for DNS and DOHDOT checks to indicate the type of DNS entry to query - String set to one of: 'ANY', 'A', 'AAAA', 'CNAME', 'MX', 'NS', 'PTR', 'SOA', 'SRV', 'TXT'.
dnstoresolve - optional string for DNS and DOHDOT checks - The FQDN of the DNS query
dnsrd - optional boolean for DNS check - DNS RD (Recursion Desired) bit - defaults to true. If you're using CloudFlare DNS servers, set this to false.
transport - optional string for DNS and SIP checks transport protocol - defaults to 'udp' but 'tcp' is also supported. 'tls', 'ws', and 'wss' are also supported on SIP checks.
follow - optional boolean used for HTTP, HTTPCONTENT and HTTPADV checks. If true, the check will follow up to four redirects. The HTTPADV check only supports follow for GET requests.
email - optional string used for SMTP checks.
port - optional/required positive integer for DNS, FTP, NTP, PORT, SSH type checks - used for check types that support port fields separate from the target address. HTTP and HTTPCONTENT will ignore this field as the port must be set in the target in standard URL format. This field is required by PORT and NTP checks.
username - optional string for FTP, IMAP4, MYSQL, POP3, SMTP, and SSH type checks - HTTP, HTTPCONTENT, HTTPADV, and HTTPPARSE will ignore this field as the username must be set in the target in standard URL format.
password - optional string for FTP, IMAP4, MYSQL, POP3, SMTP and SSH type checks - Note that this is going to be passed back and forth in the data, so you should always be sure that credentials used for checks are very limited in their access level. See our Terms of Service. HTTP, HTTPCONTENT, and REDIS will ignore this field as the password must be set in the target in standard URL format.
query - optional string for PGSQL, MYSQL, and MONGODB check types - query to send to the database server.
secure - optional string to specify whether the IMAP4, MYSQL, SMTP, and POP3 checks should use SSL/TLS for the check. Can be set to "false" or "ssl" or, for SMTP check, "starttls".
sshkey - optional string to specify the ID of a SSH private key to be used in the SSH check. SSH private keys are set in the Account Settings.
verify - optional string to set whether or not to verify the SSL certificate (SMTP, IMAP4, POP3, DOHDOT, PGSQL check types) or DNSSEC (DNS check type only). Can be "true" or "false".

hosts - optional object used for hosts list for the REDIS check, with an arbitrary (by default random) string as the key. Each object in the list must include the 'host' element and may include optional 'port' and 'password' elements for each host. For example:

"hosts": {
    "HSGWNS": { "host": "rediscluster1.example.com", "port":22678, "password":"myclusterhostpassword"},
    "HKUNEA": { "host": "rediscluster2.example.com", "port":32678, "password":"mysecondhostpassword"},
    "HAIMEJ": { "host": "rediscluster3.example.com", "port":32678, "password":"mylasthostpassword"}
}

ignore - optional string for the RBL and SIP check types. Specifies RBL lists to ignore. Multiple lists can be added by including them in the string, separated by commas. Specifies response codes to ignore for the SIP check type. Add multiple response codes by separating them with a comma.
invert - optional string for FTP, HTTPCONTENT, HTTPADV, NTP, PORT, SSH type checks - used for 'Does not contain' functionality in checks. Default is 'false' - Set to 'true' to invert the content type match.
warningdays - optional positive integer for SSL, WHOIS, POP3, IMAP4, and SMTP checks - number of days before certificate (or domain for WHOIS) expiration to fail the check and send a notification.
fields - optional object used for fields to parse from the HTTPPARSE, SNMP, MONGODB, MYSQL, or PGSQL response. This is a keyed list of fields, with an arbitrary (by default random) string as the key. Each object in the list can include three elements: name, min and max and for the PGSQL, MYSQL, and MONGO types, a fourth element of 'match' is available for string match. For example:
```
"fields": {
    "LSGWNS": { "name": "processmem.rss", "min":10000000, "max":999999999}
}
```
postdata - optional string that can be used in the HTTPADV check as an alternative to the data object. postdata should be a single string to post.
data, receiveheaders, sendheaders - these are optional objects used by HTTPADV ('data' can also be used for CLUSTER checks - see blow - 'sendheaders' can be used for DOHDOT and HTTPPARSE). They are formatted as key:value pairs. For example, to send a header setting the Content-Type to "application/json" the sendheaders object should look like this:
```
"sendheaders": {
    "Content-Type": "application/json"
}
```
data for CLUSTER, SPEC10DNS, and SPEC10RDDS checks (can also be used by 'HTTPADV' checks, see above). Must be formatted as key:value pairs of check ID and '1' to list the checks associated with this cluster. Set the value to "0" to remove that check ID. Example:
```
"data": {
    "201205050153W2Q4C-0J2HSIRF": "1",
    "201205050153W2Q4C-4RZT8MLN": "1",
    "201205050153W2Q4C-IOPPFQOT": "0"
}
```
database - optional string for MONGODB and MYSQL check type.
edns - optional object used to send EDNS(0) OPT psudo-records in a DNS query in the DOHDOT check type. Must be formatted as key:value pairs. The key must parse to a positive integer (code). For example:
```
"edns": {
    "65285": "494373709abcdef067678"
}
```
method - optional string used by the HTTPADV and DOHDOT checks to specify the HTTP method. For the HTTPADV check, value can be one of: GET, POST, PUT, HEAD, TRACE, or CONNECT. For DOHDOT, value can be GET or POST.
statuscode - optional positive integer specifying the expected HTTP status code in the response to an HTTPADV or DOHDOT check.
ipv6 - optional boolean specifying the check should run against an ipv6 address - PING, HTTP, HTTPCONTENT, HTTPADV, MYSQL, WHOIS, and DOHDOT checks.
namespace - optional string for MONGODB collection.
oldresultfail - optional boolean specifying if a PUSH or AGENT check should fail if results are 'old'. Old is defined in minutes by check interval multiplied by check sens. If set to false, if the AGENT or PUSH stops sending in results, the check will not fail.
redistype - optional string. Can be "standalone"(default), "sentinel", or "cluster". REDIS check only.
regex - optional boolean/string to set whether the 'contentstring' element is a regular expression or just a string to be matched. Can be "true"/true/1 or "false"/false/0. HTTPCONTENT and HTTPADV only.
sentinelname - string required if redistype is set to "sentinel". Set it to the "master-name" in your sentinel configuration. REDIS check only.
servername - optional string to specify the FQDN sent to SNI services in the SSL check.
snmpv - optional string specifying the SNMP version the check should use. Valid values are "1" and "2c". Defaults to "1" - SNMP check only.
snmpcom - optional string specifying the SNMP community indicator that should be used. Defaults to 'public' - SNMP check only.
verifyvolume - optional boolean to enable the volume detection feature - AUDIO check only.
volumemin - optional integer (acceptable range -90 to 0) used by the volume detection feature - AUDIO check only.
whoisserver - optional string specifying the WHOIS server FQDN or IPv(4/6) to query - WHOIS check only.

Fields by check type

All checktype use target, sens, threshold. Most checks also support additional fields:

AGENT - checktoken, oldresultfail
AUDIO - verifyvolume, volumemin
CLUSTER - data
DOHDOT - contentstring, dnstoresolve, dnstype, verify (for SSL), sendheaders, method, edns, ipv6, clientcert, dohdot
DNS - contentstring, dnssection, port, dnstoresolve, dnstype, dnsrd, transport, verify (for DNSSEC)
FTP - invert, conteststring, port, password, username
HTTP - ipv6
HTTPADV - invert, contentstring, regex, data, method, postdata, receiveheaders, sendheaders, statuscode, ipv6, clientcert
HTTPCONTENT - invert, contentstring, regex, ipv6
HTTPPARSE - sendheaders, fields
IMAP4 - port, verify, username, password, secure, warningdays
MONGODB - database, namespace, query, fields
MTR - ipv6
MYSQL - port, username, password, secure, ipv6, database, query, fields
NTP - invert, port
PGSQL - query, fields, verify
PING - ipv6
POP3 - port, verify, password, secure, username, warningdays
PORT - invert, port
PUSH - fields, checktoken, oldresultfail
RBL - ignore
RDP - no additional fields
REDIS - redistype, hosts, sentinelname
SIP - transport, ignore
SMTP - invert, port, verify, email, password, secure, username, warningdays
SNMP - fields, snmpv, snmpcom
SPEC10DNS - data
SPEC10RDDS - data
SSH - invert, contentstring, port, password, username, sshkey
SSL - warningdays, servername
WEBSOCKET - invert, contentstring, data
WHOIS - whoisserver, ipv6, invert, contentstring, warningdays

Request example:

curl -X PUT -d'json={"threshold":4, "target":"http://www.example.com/index.html", "type":"HTTP", "enabled":"true", "notifications":[{"SKTUSP":{"delay":0,"schedule":"Days"}}]}' 'https://api.nodeping.com/api/1/checks/201205050153W2Q4C-1FOC0YYM'

Response example:

{
  "_id": "201205050153W2Q4C-1FOC0YYM",
  "_rev": "49-5069940f2a95fc6ae5564e329da755bd",
  "customer_id": "201205050153W2Q4C",
  "label": "Site 2",
  "interval": 1,
  "notifications": [ { "SKTUSP": {"delay":0,"schedule":"Days"} } ],
  "type": "HTTP",
  "status": "modified",
  "modified": 1337744587374,
  "enabled": "active",
  "public": false,
  "parameters": {
    "target": "http://www.example.com/index.html",
    "threshold": 4,
    "sens": "2"
  },
  "state": 1,
  "firstdown": false
}

DELETE

Delete a check

id - required string - Check id of the check you want to delete.
customerid - required string when deleting a check on a subaccount - customer id of the subaccount the check belongs to.

Request example:

curl -X DELETE 'https://api.nodeping.com/api/1/checks/201205050153W2Q4C-0J2HSIRF'

Response example:

{"ok":true,"id":"201205050153W2Q4C-0J2HSIRF"}

Disable Checks

Disable or re-enable checks. This call returns an object with the number of checks that were disabled using this call (disabledall), the number of checks that were disabled by other means, and the number of checks that are currently still enabled. If optional filters are provided, only checks that match the filters will be disabled. The filters are additive, for example: supplying both 'label' and 'target' filters will only disable checks that match both. When called on a parent account, this call does not disable checks in subaccounts. You have to make a separate call with the subaccount customerid in order to disable checks within subaccounts. Checks disabled with this call can also be re-enabled in the NodePing web UI under 'Account Settings'.

customerid - required string when disabling all checks on a subaccount - customer id of the subaccount.
disableall - required - PUT method only, 'true' or 'false'. Set to 'true' to disable all checks on an account (does not effect subaccounts). Set to 'false' to re-enable those checks that had been disabled via this method. This will not re-enable checks that were previously disabled using the 'enabled' element listed above. When 'disableall' is set, all other data is ignored in the PUT so do not set this element with check modification info.
type - optional regex string - will disable any check that matches the regex provided against the 'type' field of your checks.
label - optional regex string - will disable any check that matches the regex provided against the 'label' field of your checks.
target - optional regex string - will disable any check that matches the regex provided against the 'target' field of your checks.

Request example:

curl -X PUT 'https://api.nodeping.com/api/1/checks?disableall=true'

Response example:

{"disableall":3,"disabled":0,"enabled":0}