Documentation

API Reference :: checks

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. If absent, the call will return a list of checks.
  • lastresult - optional - only valid if retrieving one check. 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.

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.


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: AUDIO, CLUSTER, DNS, FTP, HTTP, HTTPCONTENT, HTTPPARSE, HTTPADV, IMAP4, MYSQL, NTP, PING, POP3, PORT, PUSH, RBL, RDP, SIP, SMTP, SNMP, SSH, SSL, WEBSOCKET, WHOIS
  • target - required on create (except for DNS 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 integer, 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.
  • 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.
  • runlocations - optional string or json array - This is a geographical region where our probe servers are located. Currently this can be an one or more of the following: 'nam' for North America, 'eur' for Europe, 'eao' for East Asia/Oceania, or 'wlw' for world wide. If omitted, the account's default location setting is used.
  • homeloc - optional string or boolean false (available only with Provider 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 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.
  • sens - optional 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.

The following are only relevant for certain types:

  • checktoken - read-only field on PUSH checks - can request server-side re-generation by setting this field to 'reset'.
  • contentstring - optional string for DNS, HTTPCONTENT, HTTPADV, FTP, SSH, WEBSOCKET, WHOIS type checks - the string to match the response against.
  • dnstype - optional string for DNS checks to indicate the type of DNS entry to query - String set to one of: 'ANY', 'A', 'AAAA', 'CNAME', 'MX, 'NS, 'PTR', 'SOA', 'TXT'.
  • dnstoresolve - optional string for DNS type checks - The FQDN of the DNS query
  • dnsrd - optional boolean for DNS RD (Recursion Desired) bit - defaults to true. If you're using CloudFlare DNS servers, set this to false.
  • transport - optional string for DNS transport protocol - defaults to 'udp' but 'tcp' is also supported.
  • 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 IMAP and SMTP checks.
  • port - optional/required 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, IMAP, POP, SMTP and SSH type checks - HTTP and HTTPCONTENT will ignore this field as the username must be set in the target in standard URL format.
  • password - optional string for FTP, IMAP, POP, 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 and HTTPCONTENT will ignore this field as the password must be set in the target in standard URL format.
  • secure - optional string to specify whether the IMAP, SMTP, and POP checks should use TLS for the check. Can be set to "false" or "ssl".
  • verify - optional string to set whether or not to verify the certificate. Can be "true" or "false".
  • ignore - optional string for the RBL check type, specifies RBL lists to ignore. Multiple lists can be added by including them in the string, separated by commas.
  • 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 integer for SSL, WHOIS, POP, IMAP, 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 HTTPADV, HTTPPARSE, and SNMP response. This is a keyed list of fields, with an arbitrary (by default random) string as the key. Each object in the list should include three elements: name, min and max. 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). 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 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. Example:
    "data": {
        "201205050153W2Q4C-0J2HSIRF": "1",
        "201205050153W2Q4C-4RZT8MLN": "1",
        "201205050153W2Q4C-IOPPFQOT": "1"
    }
    
  • method - optional string used by the HTTPADV check to specify the HTTP method. It can be one of GET, POST, PUT, HEAD, TRACE, or CONNECT.
  • statuscode - optional integer specifying the expected status code in the response to an HTTPADV check.
  • ipv6 - optional boolean specifying the check should run against an ipv6 address - PING, HTTP, HTTPCONTENT, HTTPADV, WHOIS checks.
  • 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.
  • 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:

  • AUDIO - no additional fields
  • CLUSTER - data
  • DNS - contentstring, port, dnstoresolve, dnstype, dnsrd, transport
  • FTP - invert, conteststring, port, password, username
  • HTTP - ipv6
  • HTTPADV - invert, contentstring, data, method, postdata, receiveheaders, sendheaders, statuscode, ipv6
  • HTTPCONTENT - invert, contentstring, ipv6
  • HTTPPARSE - fields
  • IMAP4 - port, verify, email, password, secure, username, warningdays
  • MYSQL - no additional fields
  • NTP - invert, port
  • PING - ipv6
  • POP3 - port, verify, password, secure, username, warningdays
  • PORT - invert, port
  • PUSH - fields, checktoken
  • RBL- ignore
  • RDP- no additional fields
  • SIP - no additional fields
  • SMTP - invert, port, verify, email, password, secure, username, warningdays
  • SNMP - fields, snmpv, snmpcom
  • SSH - invert, contentstring, port, password, username
  • SSL - warningdays
  • 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", "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}

If you have any questions, get in touch at support@nodeping.com, or use our Contact form.