Remote Actions API
Trigger and query remote actions using the Nexthink public API, giving you the flexibility to create integrations with external applications such as ServiceNow. Using APIs helps remove complexity as IT teams don’t have to access multiple applications to carry out their work.
Setting up API credentials
To set up an integration with the Nexthink API, you must first create a set of API credentials in your instance that the external application or service will use to access the API and send requests to Remote Actions. Refer to the API Credentials documentation for more information.
Configuring Remote Actions for API requests
Create a new remote action or edit an existing one as described in the Manage Remote Actions documentation.
Under the General tab, check the API check box.
API Checkbox
Click on the Save remote action button.
The remote action is now available for API calls.
Copying remote action ID
To trigger a remote action via the API, you must know its ID.
Select Remote Actions from the main menu.
Click on the Manage remote actions button at the bottom of the navigation panel.
Find the remote action you need the ID for and click on the action menu on the right side of the row to Copy NQL ID.
Save the remote action ID for later use.
Extract the remote action ID by querying it from the API. See the section below.
Calling the API examples
Getting an authentication token
Get a token from the API using a client secret
and client ID
.
Here is an example of a call to get a token.
- the name of the instance.
- the name of the region:
us
: United Stateseu
: European Unionpac
: Asia-Pacific regionmeta
: Middle East, Turkey and Africa
If the call is successful, the response is as follows, and the access_token
field contains the token.
The token has a 15-minute lifespan, after which you must request a new token.
Getting a list of all remote actions
Use the generated token to get a list of remote actions within your Nexthink instance.
GET
The API returns all the remote actions, including their configuration information, in a JSON format. The following is an example of a JSON response:
Pass query parameters in the URL to filter the returned list.
Remote actions with Windows scripts
The following example returns remote actions that only have Windows scripts.
GET
Get a specific remote action
Retrieve the configuration of a specific remote action using the generated token.
This is similar to the call above that gets all remote actions, except in this call, you pass the URL-encoded ID of the remote action. For example, if the ID is #ExampleRA
, you have to URL-encode it and send it as the value of the nql-id
parameter nql-id=%23ExampleRA
.
GET
Triggering a remote action
Execute a remote action using the generated token and the ID of the remote action.
POST
In the body, you must specify the following parameters in JSON format:
remoteActionId
(String): the ID of the remote action to execute.
params
(Object | Key Pair): any parameters to send to the script. Leave the object empty if there are none.
devices
(Array): Nexthink Collector IDs of the devices that the remote action should be executed on.
To get the Collector ID, lookup the device.collector.id
field in an NQL investigation using the devices
object.
Example:
After successfully sending the call, you get the following fields in response:
requested
: the Nexthink ID of the request created that spawned the executions. Use this ID to query remote action executions in NQL.
expiresInMinutes
: the amount of time in minutes before the execution will expire if a targeted device does not come online to process it.
Example:
Last updated