# 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 <a href="#remoteactionsapi-settingupapicredentials" id="remoteactionsapi-settingupapicredentials"></a>

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](/platform/~/changes/Sh4xqs4GDClkDKT9Hvux/user-guide/administration/account-management/api-credentials.md) documentation for more information.

## Configuring Remote Actions for API requests <a href="#remoteactionsapi-configuringremoteactionsforapirequests" id="remoteactionsapi-configuringremoteactionsforapirequests"></a>

1. Create a new remote action or edit an existing one as described in the [Manage Remote Actions](/platform/~/changes/Sh4xqs4GDClkDKT9Hvux/user-guide/remote-actions/managing-remote-actions.md) documentation.
2. Under the **General** tab, check the **API** check box.<br>

   <figure><img src="/files/mVGFhq3mFCosRvBEsgrV" alt="API Checkbox"><figcaption></figcaption></figure>

   API Checkbox
3. Click on the **Save remote action** button.

The remote action is now available for API calls.

## Copying remote action ID <a href="#remoteactionsapi-copyingremoteactionid" id="remoteactionsapi-copyingremoteactionid"></a>

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 <a href="#remoteactionsapi-callingtheapiexamples" id="remoteactionsapi-callingtheapiexamples"></a>

#### Getting an authentication token <a href="#remoteactionsapi-gettinganauthenticationtoken" id="remoteactionsapi-gettinganauthenticationtoken"></a>

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]'
```

* \- the name of the instance.
* \- 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 1&#x35;**-**&#x6D;inute lifespan, after which you must request a new token.

### Getting a list of all remote actions <a href="#remoteactionsapi-gettingalistofallremoteactions" id="remoteactionsapi-gettingalistofallremoteactions"></a>

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
                }
            ]
        }
    },
```

{% hint style="info" %}
Pass query parameters in the URL to filter the returned list.
{% endhint %}

### Remote actions with Windows scripts <a href="#remoteactionsapi-remoteactionswithwindowsscripts" id="remoteactionsapi-remoteactionswithwindowsscripts"></a>

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 <a href="#remoteactionsapi-getaspecificremoteaction" id="remoteactionsapi-getaspecificremoteaction"></a>

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 <a href="#remoteactionsapi-triggeringaremoteaction" id="remoteactionsapi-triggeringaremoteaction"></a>

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.

{% hint style="info" %}
To get the Collector ID, lookup the `device.collector.id` field in an NQL investigation using the `devices` object.
{% endhint %}

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
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nexthink.com/platform/~/changes/Sh4xqs4GDClkDKT9Hvux/user-guide/remote-actions/managing-remote-actions/remote-actions-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.