SimpleHelp's Toolbox Scripting API turns your existing scripts into fleet-wide workflows: sending user notifications, triggering alerts, pulling log files, and chaining actions across machines, all from within a single Tool run. This post walks through six practical examples, from popping up a message when an alert fires to triggering Tools automatically from an external system via the Web API.
Most SimpleHelp administrators know they can write Toolbox scripts to run during sessions or via the Access tab. Fewer realise that a set of server-side functions, the Scripting API, can be called directly from within those scripts. Want to directly pull machine performance data? Automate file transfers between your remote machines? Show notification pop-ups to users, or to your Technicians, or to an email address? Conditionally chain Tool actions across different machines? Read on.
This post is a practical introduction to what the Toolbox Scripting API actually does, why it matters in production, and how to use it for problems you have probably already encountered. You can find the user guide here.
With the Scripting API, a Tool script goes from a script that runs on a single machine and produces a single output to a much more versatile and powerful instrument that can:
The practical effect is that you can build workflows that span machines, respond dynamically to what they find, and perform what you need them to all within SimpleHelp in a single Tool run.
SimpleHelp gives you two distinct scripting surfaces:
The Toolbox Scripting API provides a set of embedded functions you write directly into your Toolbox scripts (Batch, PowerShell, Bash). These are OS agnostic, saving you time writing several scripts to get the same data or perform the same actions. They run either before your script executes (PRE functions used to pull in data, download files, or collect input) or after it completes (POST functions used to send notifications, push files, log results, or trigger further actions).
The Web API (v5.1+) is a standard HTTP API you call from external systems to securely get data from and spawn actions directly on your SimpleHelp server to a monitoring platform, a CI/CD pipeline, a custom dashboard or just to a log file on disk. List machines’ availability, fetch monitoring data, manage technician accounts, query session history for billing, or use it to launch Tools.
With great power comes great responsibility: Unless you're very sure about what you're doing, it's OK to have the server API launch Tools, but it's not a great idea from a security standpoint to have the Toolbox API calling the Web API since you don't really want to be passing your API tokens about! As always, our security guide has advice on making sure you're adhering to best practices.
There are two kinds of calls offered by the API:
PRE functions are resolved by the SimpleHelp server before your script is sent to the remote machine. PRE calls include:
POST functions are embedded in your script. They can reference script variables and can be embedded in your script's conditional structures to control which actions are taken. Some examples:
They can also fetch and set Machine Properties to associate any data you like with your remote machines, and can be used like Tags or to store machine data server-side so it's available even when the machine's offline (software versions, network or physical locations, organisational divisions, anything you like). See the Toolbox Scripting API guide here for the full list of functions on offer.
The problem: You have a Monitoring Alert configured to trigger when a machine's primary disk is 90% full. The basic Alert actions let you send emails or run a command on the machine, but you don't want to have to set up separate Alerts for every OS with appropriate commands, and you want the end user on that machine to see a pop-up message rather than just hope they're checking their email regularly.
The solution: Use ServerUtilsNotifyMachines in a Tool. Add the Run a Tool action to your Alert and you've automated disk space warnings for users.
# Get the disks with <10% free space remaining
$disksNearlyFull = (
Get-CimInstance Win32_LogicalDisk |
Where-Object {
$_.Size -and ($_.FreeSpace / $_.Size) -lt 0.10
} |
ForEach-Object {
"{0} {1:P1} free" -f $_.DeviceID, ($_.FreeSpace / $_.Size)
}
) -join '; '
# Display the popup on the affected machine
ServerUtilsNotifyMachines(
@ThisMachine(),
"Disk space warning!",
"The following disks have less than 10% free space remaining: $disksNearlyFull"
)Write your scripts for you. We have Cyana for that; See our SimpleHelp Dispatch for more information about Cyana and Cyana setup guide for more.
Run automatically on a schedule providing a full end-to-end automated RMM platform. Unless you pair it with our Monitoring Alerts by setting your Tool as a Custom Threshold, then they absolutely can (See our guide here).
If you have never used the Scripting API before, the fastest path is to take a Toolbox script you already use and add a single POST call to it — ServerUtilsLog is a good starting point, since it is harmless and immediately shows you that the API is working.
From there, ServerUtilsNotifyMachines and ServerUtilsSendEmail are the two functions most administrators find immediately useful. Between them, they cover the majority of "I wish this script could tell someone what it found" use cases without any additional infrastructure.
The full function reference is in SimpleHelp's Toolbox Scripting Guide, and the Web API endpoint documentation is at guides.simple-help.com/simplehelp-integration-api-v1.
SimpleHelp is a unified remote support and RMM platform. Learn more at simple-help.com.
