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

1. Create a new remote action or edit an existing one as described in the Manage Remote Actions documentation.

2. Under the General tab, check the API check box.
   

   

3. 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.

1. Select Remote Actions from the main menu.

2. Click on the Manage remote actions button at the bottom of the navigation panel.

3. 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.

4. 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.

curl --location --request POST 'https://<customer>.api.<region>.nexthink.cloud/api/v1/token'\ --header 'Authorization: Basic [Base64 encoded clientId:clientSecret]'

• <customer> - the name of the instance.

• <region> - the name of the region:

  • us : United States

  • eu : European Union

  • pac : Asia-Pacific region

  • meta : Middle East, Turkey and Africa

If the call is successful, the response is as follows, and the access_token field contains the token.

{
    "token_type": "Bearer",
    "expires_in": 900,
    "access_token": "example",
    "scope": "service:integration"
}

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

https://<customer>.api.<region>.nexthink.cloud/api/v1/act/remote-action/

The API returns all the remote actions, including their configuration information, in a JSON format. The following is an example of a JSON response:

    {
        "id": "#ExampleRA",
        "uuid": "5g5158g0-cd00-46be-9bfb-a9283ba800b",
        "name": "Example Remote Action",
        "purpose": [
            "DATA_COLLECTION"
        ],
        "targeting": {
            "apiEnabled": false,
            "manualEnabled": true,
            "manualAllowMultipleDevices": true
        },
        "scriptInfo": {
            "runAs": "LOCAL_SYSTEM",
            "timeoutSeconds": 120,
            "hasScriptWindows": true,
            "hasScriptMacOs": false,
            "inputs": [
                {
                    "id": "name",
                    "name": "Name",
                    "usedByWindows": true,
                    "usedByMacOs": false,
                    "options": [
                        "X"
                    ],
                    "allowCustomValue": true
                },
                {
                    "id": "StatusChange",
                    "name": "Status Change",
                    "usedByWindows": true,
                    "usedByMacOs": false,
                    "options": [
                        "On"
                    ],
                    "allowCustomValue": true
                },
                {
                    "id": "SetStartTypeTo",
                    "name": "Set Start Type To",
                    "usedByWindows": true,
                    "usedByMacOs": false,
                    "options": [
                        "X"
                    ],
                    "allowCustomValue": true
                }
            ],
            "outputs": [
                {
                    "id": "UpdatedServiceStatus",
                    "name": "Updated Service Status",
                    "type": "list_of_strings",
                    "usedByWindows": true,
                    "usedByMacOs": false
                }
            ]
        }
    },

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

https://<customer>.api.<continent>.nexthink.cloud/api/v1/act/remote-action/?hasScriptWindows=true&hasScriptMacOs=false

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

https://<customer>.api.<continent>.nexthink.cloud/api/v1/act/remote-action/details?nql-id=%23ExampleRA

Triggering a remote action

Execute a remote action using the generated token and the ID of the remote action.

POST

https://<customer>.api.<continent>.nexthink.cloud/api/v1/act/execute

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:

{
    "remoteActionId": "#ExampleRA",
    "params": {"StartType": "Automatic", "StatusChange": "On", "SetStartTypeTo": "Manual"},
    "devices": [
        "2b2frs41-bbb3-4e50-ba45-7ba09c3a7f16","8ebe8051-4g1b-4617-8148-df7a56c307b3","31bc219c-fb9g-47ba-8fc1-18cdf66b5e5a"
    ]
}

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:

{
    "requestId": "7fbd96a7-b717-43a7-8973-9c6adbca3a56",
    "expiresInMinutes": 10080
}