# Triggering Remote Actions Via Their API (classic)

Some functionality described in this article refers to Finder (classic)

{% hint style="info" %}
Nexthink Finder is a Windows-only desktop application whose functionality is now available within the Nexthink web interface. Nexthink can now be used directly from a browser and most functions no longer require an additional desktop application.
{% endhint %}

The API of Nexthink Act makes it possible to trigger remote actions programmatically, enabling their integration with third-party products such as self-service portals or ticketing systems.

The API of remote actions is exposed by the Nexthink web interface as a REST API. The present article documents Act API v2.

## Prerequisites <a href="#triggeringremoteactionsviatheirapi-classic-prerequisites" id="triggeringremoteactionsviatheirapi-classic-prerequisites"></a>

For a remote action to be triggered through the Act API, the following prerequisites apply:

* The remote action can be manually triggered.
* The remote action is triggered on behalf of a user whose profile includes Finder access with the option **Allow API of remote actions** ticked.

## Calling the Act API <a href="#triggeringremoteactionsviatheirapi-classic-callingtheactapi" id="triggeringremoteactionsviatheirapi-classic-callingtheactapi"></a>

The Nexthink web interface exposes the Act API as a REST API under the URL:

`https://[portal.company.com]/api/remoteaction/v2/run`

In the URL, substitute `[portal.company.com]` for the external DNS name of your Nexthink web interface.

\
To trigger a remote action, submit a POST request to the URL of the API (note that GET requests are not supported, returning a 404 error) with a JSON payload containing two parameters:

| Name                 | Description                                                                                                           |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `requestUid`         | (Optional) Identifier of the request for logging purposes.                                                            |
| `remoteActionUid`    | Identifier of the remote action.                                                                                      |
| `deviceUids`         | List of device identifiers to target.                                                                                 |
| `engineDatabaseUids` | (Optional) List of Engine identifiers to target.                                                                      |
| `timeoutSeconds`     | (Optional) Request timeout in seconds. Overrides default timeout configured in the the Nexthink web interface (60 s). |
| `params​`            | (Optional) List of parameter inputs and values​. Unknown parameter names are ignored.                                 |

The call is dispatched either to all the Engines connected to the Nexthink web interface or to the indicated Engines only and returns either when the Nexthink web interface receives the answer from the targeted Engines or after the specified timeout is elapsed. A successful response from the Nexthink web interface does not guarantee the execution of the remote action on the selected devices (see the list of codes for Engine responses below).

#### Obtaining the UIDs of remote actions, devices and Engines from Finder (classic) <a href="#triggeringremoteactionsviatheirapi-classic-obtainingtheuidsofremoteactions-devicesandenginesfromfind" id="triggeringremoteactionsviatheirapi-classic-obtainingtheuidsofremoteactions-devicesandenginesfromfind"></a>

To get the UID of a remote action:

1. Log in to Finder as a user with permission to edit remote actions.
2. Locate the desired remote action under the **Remote actions** section of the left-hand side menu.
3. Right-click the remote action name.
4. Select **Export > Remote action Uid to clipboard**.
5. In your request editor, press **Ctrl+V** to paste the UID into the JSON payload.

Find the UIDs of the devices through either:

* The Finder: Display field **UID** of the device object.
* NXQL: Retrieve the **device\_uid** field of the device objects, for instance:

`(select device_uid (from device))`

To target specific Engines, get the UID of the database on each Engine via the [List Engines API](https://docs.nexthink.com/platform/~/changes/Sh4xqs4GDClkDKT9Hvux/integrations/api-and-integrations-classic/other-integrations-classic/list-engines-api-classic).

#### HTTP headers <a href="#triggeringremoteactionsviatheirapi-classic-httpheaders" id="triggeringremoteactionsviatheirapi-classic-httpheaders"></a>

Send your POST request to the API of remote actions with the following HTTP headers to specify JSON content and basic authentication:

`Content-type: application/json`

`Authorization: Basic [base-64(user:password)]`

Replace `[base-64(user:password)]` with the credentials (in base-64 encoding) of a Nexthink user who has the right to access the API of remote actions.

## Response <a href="#triggeringremoteactionsviatheirapi-classic-response" id="triggeringremoteactionsviatheirapi-classic-response"></a>

#### Successful response <a href="#triggeringremoteactionsviatheirapi-classic-successfulresponse" id="triggeringremoteactionsviatheirapi-classic-successfulresponse"></a>

When successful, a call to the Act API v2 returns a list of responses from each targeted Engine with HTTP code 200.

| Name          | Description                                                                                                                                                                                   |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `databaseUid` | The identifier of the targeted Engine                                                                                                                                                         |
| `code`        | <ul><li>ok</li><li>timeout</li><li>engine\_error</li><li>not\_connected</li><li>excludedUnknown <code>databaseUid</code></li><li>no\_permissionUser has no permission on the Engine</li></ul> |
| `message`     | Possible additional message from the Engine                                                                                                                                                   |

### Error response <a href="#triggeringremoteactionsviatheirapi-classic-errorresponse" id="triggeringremoteactionsviatheirapi-classic-errorresponse"></a>

When unsuccessful, a call to the Act API v2 returns an error response with HTTP code depending on the type of error.

| Name    | Description                           |           |
| ------- | ------------------------------------- | --------- |
| `code`  | Error code, one of:                   | HTTP code |
|         | INVALID\_REQUEST\_JSON                | 400       |
|         | INVALID\_REQUEST\_CONTENT             | 400       |
|         | INTERNAL\_ERROR                       | 500       |
|         | CONTENT\_TYPE                         | 400       |
|         | ENCODING                              | 400       |
|         | NO\_REMOTE\_ACTION\_UID               | 400       |
|         | NO\_DEVICES                           | 400       |
|         | TOO\_MANY\_DEVICES                    | 400       |
|         | INVALID\_ACTION\_UID                  | 400       |
|         | INVALID\_DEVICE\_UID                  | 400       |
|         | NO\_PERMISSION                        | 403       |
|         | UNKNOWN\_OR\_DISABLED\_REMOTE\_ACTION | 400       |
|         | NO\_MANUAL\_EXECUTION                 | 400       |
|         | NO\_ENGINES\_TO\_TARGET               | 403       |
| `error` | Description of the error code.        |           |

## Examples <a href="#triggeringremoteactionsviatheirapi-classic-examples" id="triggeringremoteactionsviatheirapi-classic-examples"></a>

### Target all Engines <a href="#triggeringremoteactionsviatheirapi-classic-targetallengines" id="triggeringremoteactionsviatheirapi-classic-targetallengines"></a>

Example of a request that targets all Engines and its response in JSON format.

```
// request
{
 "requestUid": "123",
 "remoteActionUid": "07844969-1889-4de3-9026-020af94be855",
 "deviceUids": ["da2add909a144e8235453f88dc45172f","4423e4c059b2c72ee9382e135888bef7",
 "13ea2b236e6833ffe6045a7715968cba","3537e2f2eb0d5f2152da59e7cbcb505b"]
}


// response
// Status 200
// Body:
[
    {
 "databaseUid": "86acc8511251ec444d3a75bac33a23c7",
 "code": "ok",
 "message": ""
    },
    {
 "databaseUid": "a4690014774dcc32b919c27d616166f7",
 "code": "ok",
 "message": ""
    },
    {
 "databaseUid": "ce80dddfdb7a5c2346c4ac184b7d6a54",
 "code": "engine_error",
 "message": "Error in request to engine [172.16.5.177:999]: no license"
    }
]
```

### Target one Engine <a href="#triggeringremoteactionsviatheirapi-classic-targetoneengine" id="triggeringremoteactionsviatheirapi-classic-targetoneengine"></a>

Example of a request that targets one Engine and its response in JSON format.

```
// request
{
 
 "requestUid": "123",
 "remoteActionUid": "07844969-1889-4de3-9026-020af94be855",
 "deviceUids": ["da2add909a144e8235453f88dc45172f","4423e4c059b2c72ee9382e135888bef7",
 "13ea2b236e6833ffe6045a7715968cba","3537e2f2eb0d5f2152da59e7cbcb505b"],
 "engineDatabaseUids" : ["a4690014774dcc32b919c27d616166f7"]
}
 
// response
// Status 200
// Body:
[
    {
 "databaseUid": "a4690014774dcc32b919c27d616166f7",
 "code": "ok",
 "message": ""
    }
]
```

### Error response <a href="#triggeringremoteactionsviatheirapi-classic-errorresponse.1" id="triggeringremoteactionsviatheirapi-classic-errorresponse.1"></a>

Example of a request that returns an error because the remote action disabled manual execution.

```
// request
{
 "requestUid": "123",
 "remoteActionUid": "e6bb97be-0957-49e0-9922-1a684d093858",
 "deviceUids": ["da2add909a144e8235453f88dc45172f","4423e4c059b2c72ee9382e135888bef7",
 "13ea2b236e6833ffe6045a7715968cba","3537e2f2eb0d5f2152da59e7cbcb505b"]
}
 
 
// response
// Status 400
// Body:
{
 "code": "NO_MANUAL_EXECUTION",
 "error": "Remote action not configured for manual execution"
}
```

***

RELATED TASK

* [Triggering a remote action manually](https://docs.nexthink.com/platform/~/changes/Sh4xqs4GDClkDKT9Hvux/user-guide/remote-actions/remote-actions-in-finder-classic/triggering-a-remote-action-manually-with-finder-classic)

RELATED REFERENCE

* [List Engines API](https://docs.nexthink.com/platform/~/changes/Sh4xqs4GDClkDKT9Hvux/integrations/api-and-integrations-classic/other-integrations-classic/list-engines-api-classic)