Triggering remote actions via their API


Triggering remote actions via their API


The API of Nexthink Act makes 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 Portal as a REST API.

Applies to platforms: PlatformWindows.png


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

The Portal exposes the Act API as a REST API under the URL:


In the URL, substitute [] for the external DNS name of your Portal.

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
RemoteActionUid Identifier of the remote action
DeviceUids List of device identifiers

Example of the JSON payload of a request to the API of remote actions:

  "RemoteActionUid": "b21b9377-3624-4046-8378-76244657d2d4",
  "DeviceUids" : ["da581fd269e0bc4c03b767a345fbf5d3","fa623653cd663e19a58d69519471bbef"]

The call is dispatched to all the Engines connected to the Portal and executed asynchronously, meaning that it returns immediately after the request has been validated. A successful response from the Portal does not guarantee the execution of the remote action on the selected devices. For unsuccessful responses, see the list of error conditions below.

Obtaining the UIDs of remote actions and devices

To get the UID of a remote action:

  1. Log in to the Finder as a user with the 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))

HTTP headers

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.

Error conditions

In response to a request, the Portal may send one of the following answers when something is wrong with the request:

Error type HTTP code Cause
Access Denied Unauthorized 401
  • Authentication error
Forbidden 403
  • User with insufficient permissions to run the specified remote action
Validation error Bad request 400
  • Invalid JSON
  • Invalid encoding
  • Invalid Content-type
  • Invalid or missing UID of remote action
  • Invalid or missing UIDs of devices
  • Unknown or disabled remote action
  • Manual execution of remote action not allowed
  • Too many device UIDs specified (limit of 12 000)
Unknown error Internal server error 500
  • Undefined internal error