The NodePing API and PowerShell

At NodePing we interact with our own API quite a bit from the command line.  Most of that is from bash on Linux, because that’s where we live most of our lives.  But the API works well from just about any scripting environment.  Since our documentation examples all use curl with bash syntax, it seemed like it might be a good idea to also write up some examples of using other tools.  Here, as the first installment of that effort, is a handful of examples of using PowerShell with the NodePing API.

Full disclosure: PowerShell is not an environment we spend a lot of time working with.  There are likely ways to do some of this better.  We’ve tested the example calls in this post.  Hopefully it is enough to get you started if you work with PowerShell.

Basic GET Calls

Basic calls are quite simple to make using Invoke-RestMethod.  If you have the check ID, getting a check is quite easy:

Invoke-RestMethod ‘[token]’

This returns a JSON object, which PowerShell handles easily.

_id : 201205050153W2Q4C-0J2HSIRF
description : This is the description, if the check has one.
public : False
customer_id : 201205050153W2Q4C
queue : nyI8JSL23W
interval : 1
created : 1427513104608
pro :
modified : 1510332098196
parameters : @{target=; follow=False; threshold=5; sens=2; invert=False; verify=false}
firstdown : 0
label : Keep me
runlocations : False
enable : active
uuid : bd3eha9o-z2m5-4qg2-9k8b-jqq0kiituyxz
state : 1
status : assigned
notifications : {}
type : HTTP
acctdisable : False
suspacct : False
dep : False

Note that “parameters” is another hash.  You can refer to the fields in the check as properties of the returned object, including properties that are hashes themselves.  So, for example, this will give you the check check threshold, which is part of “parameters”.

$check = Invoke-RestMethod ‘[token]’ ;

API Authentication

PowerShell doesn’t easily support basic authentication.  Since the NodePing API supports passing the token as a parameter, the easiest approach is to include it in the query string, as I did in the example above.  In most cases I prefer to pass it in the Body, as I’ll show in examples below.  If you’re working with a script its usually easiest to set a $token variable and use that throughout your script.  If you’re just sending a URL as I did in the simple GET calls above, actually putting in the query string works fine.

If you’re using the API in scripts that make several calls to the API, you might want a more reusable way to pass the token that keeps it out of your Body.  You can do this by manually building the headers.  That requires base64 encoding the credentials and then setting that using the -Headers argument. That looks something like this:

$hash = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $token,"")))

Then set the -Header argument to @{Authorization=(“Basic {0}” -f $hash)}

Or, if you are doing this several times, you will probably want to set this to a variable you can reuse.

Some sites suggest that you create a credential object using ConvertTo-SecureString and Management.Automation.PSCredential, and pass that using the -Credential argument.  However, this won’t work with the NodePing API, since the -Credential option waits for the challenge to send the authorization header.  The API is stateless, and expects the header on each request.

Put and Post Calls

We recommend that you use JSON to set fields for our API in most environments.  However, PowerShell does not automatically handle sending the body as JSON.  For POST calls, this isn’t a big deal, and you can just POST the body as it is and Invoke-RestMethod sends the data as if it were a form.  PUT and DELETE calls don’t work that way.  For those, you have to convert to JSON, or include all of your parameters in a query string.

Creating a check looks like this:

Invoke-RestMethod '' -Method Post -Body @{ 
    label='test label' 

This call will return an object with the new check.  You can add any of the other fields listed in our documentation.

Updating a check is almost the same.  This can all be done on one line, but we’ll split it out here to make it easier to see.

$data = @{ label='a new label'; type="HTTP"; interval=5; token=$token } | ConvertTo-Json
Invoke-RestMethod '' -Method Put -Body $data

Note that since we’re updating a check, we need to include the check ID.  As with the Post call, the Put call returns the updated check object.

Working with Lists of Checks

Working with a list of checks is slightly trickier.  The call returns a JSON object with a list of checks using the ID as the key.  For PowerShell, this is a hash table of hashes.  So to list checks, you would do something like this:

Invoke-RestMethod '' -Body @{ token=$token } | %{ $_.PSOBJECT.Properties.value }

This is actually fairly handy, because you can fairly easily list a specific field from the response.  For example, this lists all of the targets from all of the checks on this account:

Invoke-RestMethod '' -Body @{ token=$token } | %{ $ }

You could do all sorts of things at this point.  For example, here’s a list of all checks that include “nodeping” somewhere in the check’s target:

Invoke-RestMethod '' -Method Get -Body @{ token=$token } | %{ foreach($value in $_.PSOBJECT.Properties.value){ if($ -like "*nodeping*"){ $value } } }

This is practical as a way to find a check with a specific target up to a few thousand checks.

Getting Results

Applying the same principles should let you do just about anything with the NodePing API.  Applying the same pattern to a results call, for example:

Invoke-RestMethod '' -Method Get -Body @{ token=$token; limit=2; clean=1 }

Note that you’ll want to always include the “clean” parameter for results.  The unclean response takes more parsing.

The options available for results calls are documented here:


That’s the basics of using PowerShell to interact with the NodePing API.  With the API you can add checks, remove checks, get your results and uptime, manage contacts and notifications, and add and manage subaccounts.  Our customers use the API both for programmed integrations, and from the command line using quick scripts like the ones I demonstrated here to make quick changes to several (or lots) of checks at once.

If you’re doing interesting things with PowerShell and the NodePing API, we’d like to hear about it!  Please email support and let us know.  That’s also a great place to ask us questions.  We’re happy to help people interact with our service.

Support for Multiple Public Status Pages

Our public status report is a critical part of keeping your customers informed of your site and service status—which after all is one of the points of monitoring. Our status pages are customizable to your company, and support a custom domain so you can display your status at, or whatever is most applicable to your business.

We have had a public status page as one of our key features for some time.  Now, we’re adding support for multiple status pages on one account. For instance, NodePing has a status report page for our websites at, and one specifically for our probe servers at  Business and Provider accounts can optionally set up an SSL cert for their status pages (contact support for info how).

To create a new status report, just log into your account , and go to the “Account Settings” tab, then the “Reporting” subtab. Click “Add new status report” and add as many checks as you want to your new status report.  

We hope you will find this feature just as useful as we do.  We also have several more enhancements for public status pages coming soon.  Let us know what you think at, by posting comments here, or by using our Contact Page.

IPv6 Monitoring

NodePing now supports IPv6… mostly.

Our website and server monitoring service can now monitor IPv6 services. With real, honest-to-goodness ICMP pings as well as the funky bracket notation for URLs:


Our IPv6 support is pretty extensive.

Even though IPv6 adoption has only just crossed the 10% mark, we know many of our customers are out in front of that pack and we’re happy to keep an eye on your v6 stuff.

If you’re using hostnames that resolve to both IPv4 and IPv6, you’ll need to set up separate checks and specify the IPv6 services using the IP as our services will continue to prefer IPv4 for resolution of hostnames. The exception here is our ping check, where you can specify the protocol version to use with a hostname.  You’ll need two checks to cover both protocols.

Unfortunately there are a few caveats and addendums… A couple of our check type don’t yet support IPv6 routing – RBL and SIP checks.  Not many RBLs (Real-time BlackLists) support IPv6 addresses and our SIP check relies on a library that doesn’t support IPv6.  We’ll keep an eye on these and add IPv6 support to them when we can.

We also aren’t able to provide IPv6 monitoring from our Latin America region, sorry.  IPv6 connectivity in Latin America is nearly non-existent currently. We’re sure that will change in the future and we’ll be able to bring that online eventually as providers there start offering it. Our other regions (North America, Europe, and East Asia/Oceania) are well supported.

IPv6 support is available on all NodePing plans. If you’ve got IPv6 services that need monitoring and don’t have a NodePing account yet, please sign up for our free 15-day free trial.  We’ve got your back.


HTTP Advanced Check

Our HTTP checks for website monitoring at NodePing already include our standard HTTP Check, the HTTP Content Check that lets you verify that specific content is present or is not present in the page, and the HTTP Parse Check that allows you to track and alert on arbitrary data points in the response. Today we’re excited to announce that we’re adding the HTTP Advanced Check to our HTTP line up.

The new HTTP Advanced Check adds the following capabilities:

  • simulate a form POST to your web site and verify the expected response
  • check for arbitrary HTTP response status codes for custom API servers
  • send HTTP headers
  • verify specific HTTP headers are being received
  • send PUT, DELETE, HEAD, TRACE, or CONNECT methods

This will allow you to do more in-depth monitoring of your HTTP services. Use cases may include:

  • POST incorrect credentials to log in pages and verify the HTTP status code of 403 is returned.
  • Send mobile browser User-Agent headers and use the content checking to verify the mobile version of your site is being shown
  • Verify a PDF link is returning a PDF file by checking the return header for the correct ‘Content-Type’:’application/pdf’
  • Verify your redirect script is returning a 302 status code and not an error.

Additional information about this new check type can be found in our documentation.

The HTTP Advanced check is now available on all NodePing accounts. All accounts also include unlimited notifications, including international SMS. If you don’t have a NodePing account yet, please sign up for our free 15-day free trial.

Sendgrid’s outage impacted our notification systems

Our notification systems use Sendgrid for email delivery. Overall, Sendgrid has been very reliable and a solid service provider. Today Sendgrid had a fairly significant outage, and that has impacted the timely delivery of some of our email notifications. Obviously for a service like ours this is a big deal.

We are in the process of reviewing our notifications infrastructure to see how our failover systems can be improved to make sure our notifications always get out in a timely fashion. Our apologies to our users who were impacted by this problem.

If you have any questions about this issue, please feel free to email us at

Twitter Notifications

NodePing is happy to announce our newest notification method – twitter direct messages.  The ability to receive a twitter direct message is a great addition to our current notification system that already includes unlimited email, international SMS, and voice calls.

Twitter notifications are in testing at this point.  They are available on all accounts so please do kick the tires and let us know how things work for you at

You’ll need to follow @NodePing in order to get direct message alerts.  Then add your twitter handle in your contact record and in your check’s notification section and we’ll send you a private and discrete ‘direct message’ (not an embarrassing public tweet) when that check goes down and again when it comes back up.

Let us know in the comments how this new notification type is working for you and what you’d like to see added next – instant message (IM), HTTP POST to url, carrier pigeon, etc?

SSH Check with Content String Matching

NodePing is happy to announce the new SSH check. In its simplest use, the new SSH monitoring provides a real SSH connection for monitoring those critical SSH services, but our check can do much more than that.

Not only can we monitor the availability of your SSH services on any port, but we can also optionally have the check log in and verify the presence, or absence, of a particular string in the login response. Pairing the SSH check with a login script makes it much more powerful and flexible. With it, you can monitor much more than SSH.

In the example below, we’re going to set a login script that checks server load, available memory, and disk usage. We’ll use its simple ‘PASS‘ or ‘FAIL‘ output to trigger email and SMS alerts from NodePing when the 1 minute load average goes over 4.0, when available memory drops below 50MB, or when the disk becomes more than 90% full.

The script is a simple BASH script that relies on commonly installed programs like ‘top’, ‘free’, and ‘df’ to determine the ‘PASS’/’FAIL’ status for each of the things we’re monitoring. It’s not the prettiest thing, but it seems to work well on an Ubuntu server.

# Load average limit
# A quad-core server may be maxing out CPUs at 4.0
# Free memory floor in MB.
# Disk usage in percentage, but without the percent sign. 
# Path to the disk partition you want to monitor.

LOAD=`top -n1 | grep 'load average' | awk -F" " '{print $12}'`;
LOAD=`echo "$LOAD > $LOADLIMIT" | bc`
if [ $LOAD -eq 1 ]; then
echo "LOAD:FAIL";
echo "LOAD:PASS";

MEMUSAGE=`free -m | grep '^Mem' | awk -F" " '{print $4}'`;
if [ $MEMUSAGE -eq 1 ]; then
echo "MEM:FAIL";
echo "MEM:PASS";
DISKSPACE=`df | grep "$DISKPATH" | awk -F" " '{print $5}'`;
LEN=`expr "$DISKSPACE" : '.*'`;
LEN=`echo "$LEN-1" | bc`;
if [ $DISKSPACE -eq 1 ]; then
echo "DISK:FAIL";
echo "DISK:PASS";
# logout right away
# This SSH user is restricted for security purposes

We saved this script as ‘mylogin.bash‘ in our user’s home folder and then edited the /etc/passwd file, replacing the shell ‘/bin/bash‘ with ‘/home/testuser/mylogin.bash‘.  Don’t forget to make the script file executable with something like

chmod 0755 /home/testuser/mylogin.bash 

Now when our test user logs in, we see something like:

Last login: Thu Apr 12 22:41:33 2012 from
Connection to closed.

It’s the response text above that will be checked against our user defined content string. In our SSH check configuration, we’ll set the ‘Content string‘ dropdown to ‘Does not contain‘ and type ‘FAIL‘ in the text field.  Now when NodePing’s probe servers login via SSH and find the word ‘FAIL‘ in the response, I’ll get a notification!

But the notification just says that the SSH check failed. We won’t know what failed.  It could be the load, memory, or disk.  Instead of logging in to see, I’ll be lazy and create three separate SSH checks, all with the same host and login information, but have one check for the string ‘LOAD:FAIL‘, another check for ‘MEM:FAIL‘, and the other ‘DISK:FAIL‘.  I’ll label the one that checks the load average a nice informative name like “Load Average on test server” and the other checks something similar. Now my SMS notification say something like “SSH Check failed for: Load Average on test server“, letting me know exactly what’s failing.

NodePing provides 1000 checks run at up to 1 minute intervals for only $10/month so you’re running out of reasons not to monitor everything. If you don’t have a NodePing account yet, sign up for our free 15-day trial and kick the tires.  We think you’ll like it.

The above example is fairly simple.  You can write your own login scripts in Node.js, Python, etc to check statuses for databases, VPN connections, virus definition updates,… dang near anything!  You can find information on how to configure your SSH checks in our documentation.

How will you use the new SSH check with content string matching?  Let us know in the comments below.