> For the complete documentation index, see [llms.txt](https://docs.nexthink.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexthink.com/configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/api-calls.md).

# API Calls

API Calls let you call third-party APIs when needed to trigger actions or retrieve external data. Spark and Workspace can use them, for example, to create an incident in an ITSM tool.

## Accessing API Calls

To access the **API calls** page, navigate to **Administration** > **API Calls** from the main menu. The **API calls Administration** page opens, listing all API calls configured in this Nexthink instance.

Nexthink provides out-of-the-box API calls as system content, with pre-built integrations for tools such as Microsoft Entra ID, Microsoft Intune, Atlassian Jira, Okta and ServiceNow.

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2FdoIjgT3tE4VtxO3Qqcf7%2F2026.9_API_setup_3_Mb5Tp8Lx3e.png?alt=media&#x26;token=1e910b8b-9c56-4f2d-b4fd-7f059425c94d" alt=""><figcaption></figcaption></figure>

You can:

* Use a system API call as it is or modify it to fit your needs. Configure it, then select the features that can use it in **Triggering**. To keep the original unchanged, duplicate the system API call and customize the copy.
* Create a new API call from scratch. Refer to [Creating a new API call](#creating-a-new-api-call) for more information.

## Before you begin

Create credentials for the third-party tool that the API call connects to. Refer to [Third-party credentials](/configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/outbound-connectors/connector-credentials.md) for more information.

## Creating a new API call

Click **New API call** in the top-right corner of the page. A page opens with three tabs to configure **General** properties, **Request** and **Output**.

### Configuring the General tab

Define how the API call is identified, which connector and credentials it uses, and which features can trigger it:

* **Name**: Enter a meaningful name for the API call. This name appears on the **Administration** page.
* **NQL ID**: A unique identifier used when referencing the API call in NQL queries is created automatically. You can initially modify the suggested NQL ID, but once you save the API call, you can no longer change the NQL ID.
* **Description**: Describe what the API call does, whether it reads or changes data, and what effect it has. The agent needs it to understand which API call to make.
* **Connector (optional)**: Select the connector, the third-party platform that the API call belongs to, for example, **Entra ID**. Connectors group the API calls of a platform.
* **Credentials**: Select preconfigured credentials from the **Third-party credentials** page. Refer to the [Third-party credentials](/configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/outbound-connectors/connector-credentials.md) documentation for more information.
* **URL**: The system automatically populates this field when you select credentials.
* **Trigger**: Select the features that can use the API call.

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2FoUhKSXcqCoiPevqhJBQE%2F2026.9_API_setup_21_Qp4Vn7Ks2c.png?alt=media&amp;token=cca27a0e-7b87-4cd4-8c6b-47f82433a5e8" alt=""><figcaption></figcaption></figure>

### Configuring the Request tab

Define the request that Nexthink sends to the third-party tool.

#### Parameters

Define the values that the calling feature passes to the API call at runtime. Click **Add parameter** and complete the following fields:

* **Name**: Enter a descriptive name for the parameter.
* **ID**: A unique identifier used to reference the parameter across the **Resource**, **Payload**, and **Custom headers** sections, using the following format: `{{id}}` . It is created automatically.
* **Description**: Provide a short explanation of the purpose of the parameter.
* **Restriction**: Select whether to restrict the value that the agent passes to this parameter. **None** applies no restriction. **User** requires the value to be a property of a user. **Restrictions** currently apply only to **Spark**.
* **Restriction property**: Select the user property that the agent can pass: **AD Username**, **Email address**, **SID** or **UPN**.

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2F5HUEhV6eLaCQd7OuG3pL%2F2026.9_API_setup_5_Kf7Xh4Rw1q.png?alt=media&#x26;token=d45baeea-5af4-4f10-90db-7f8f7d4bb228" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Restrictions currently apply only to **Spark**. They ensure that **Spark** can target only the connected user when it makes an API call to a third-party tool.
{% endhint %}

Parameters are optional. Use them to accept runtime values from the calling feature, such as Spark, and insert those values into the HTTP request resource, payload, or headers.

For example, if the API call creates a support ticket, define a **Description** parameter. Spark supplies the value at runtime, and the request includes it in the ticket payload. Refer to [Configuring ticket escalation with Spark](/user-guide/spark/setting-up-and-managing-spark/ticket-escalation-with-spark.md) for more information.

#### HTTP call

Define the HTTP request that Nexthink sends to the third-party API:

* **Request method**: Select the HTTP method used, for example, GET, POST, PUT, or PATCH.
* **Resource**: Define the endpoint path or action of the third-party REST API. This determines the operation performed.
* **Payload (optional)**: Specify the data sent with POST, PUT, or PATCH methods.

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fv8PpUBaRlUZYGtanPG3U%2F2026.9_API_setup_6_Pt3Nd9Yc5u.png?alt=media&#x26;token=561d61c7-043a-40f4-a8ad-4359ccce5615" alt=""><figcaption></figcaption></figure>

#### Custom header

Define any additional HTTP headers that the third-party API requires, such as authentication tokens. Click **Add custom header** to add a header.

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2FK4AM9siOJTKFHsPURI1v%2F2026.9_API_setup_7_Vs8Bm2Gk7a.png?alt=media&#x26;token=3f53796b-8bce-488e-bf1c-ae08aa43effa" alt=""><figcaption></figcaption></figure>

### Configuring the Output tab

Click **Add output** to define a value to extract from the API response.

* **Name**: Enter a descriptive label for the output field.
* **Description**: Provide a short explanation of the data extracted from the API response.
* **Value (JSONata)**: Enter the field name returned by the API response. Use [JSONata](https://docs.jsonata.org/overview) if needed to transform the value. Enclose field names that contain whitespace or reserved characters, such as `.`, `+`, `-`, `*`, `/` or `{`, in backticks (\`).
* **Preview**: View the result of the JSONata expression applied to the response received from the API. This requires running a test first using the [Test results panel](#test-your-api-call).

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2FiMFi5bX9flYz3yCBLMwW%2F2026.9_API_setup_8_Ew6Qj5Lf4o.png?alt=media&#x26;token=b523ad88-675c-4e74-847c-3d7f9ecc8921" alt=""><figcaption></figcaption></figure>

Outputs are optional. Use them to extract values from the HTTP response, such as the response body or headers, and expose those values to the calling feature, such as Spark.

For example, if the API call creates a support ticket, define an output that returns the ticket ID from the response. If the API response is `{"result": {"number": "INC001"}}`, enter `result.number` in **Value (JSONata)** to return `INC001`.

### Test your API call

After configuring parameters and payload, use the **Test results** panel on the right side of the page to run the API call with real data, inspect responses, and identify errors. The test panel helps validate the configuration and reduce trial and error.

1. Enter a value for each parameter.
2. Click **Run test** to call the API, validate the credentials, and check connectivity to the endpoint.
3. Review the response status code, the response time, and the response of the API.
4. Verify the extracted output fields in the **Preview** column of the **Output** tab.
5. Save the API call. It appears in the table on the **API Calls** page.

{% hint style="warning" %}
The test runs a real API call. Depending on the configuration, it can update or delete data in the third-party tool.
{% endhint %}

## Managing API Calls

View the total number of API calls in the title of the table. Search for the name of the API call to narrow down the results. The table is organized by:

* **Name**: The API call name. Select the name to edit the API call.
* **Origin**: Indicates where the API call originates from.
  * **System**: An API call that Nexthink provides out of the box as system content.
  * **Custom**: An API call created on the **API Calls** page in the Nexthink web interface.
* **Description**: A short description of the API call.
* **Credentials**: The credentials used to authenticate the HTTP request.

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2FWtk4J2WsPhKQFPcUPYbE%2F2026.9_2026.9_API_setup_15_Ub7Kr2Xn9e.png?alt=media&amp;token=e41d6140-2ba6-4b76-9213-c5c9dde88028" alt=""><figcaption></figcaption></figure>

### Action menu

Click the three vertical dots of the relevant API call to open its action menu with the following options:

* **Edit**: Modify the configuration of the API call.
* **Manage tags**: Create, assign, and edit API call tags. Refer to [Tagging remote actions](/user-guide/remote-actions/setting-up-and-managing-remote-actions/managing-remote-actions.md#managingremoteactions-creatingandassigningtags) for more information.
* **Share**: Grant the **Execute** permission to other roles, for example, to let only administrators run an API call. Select the roles you want to share the API call with. Refer to [Permissions](#permissions) for more information.
* **Duplicate**: Create a copy of the API call to use as a starting point. Duplicate a system API call to customize it without changing the original.
* **Delete**: Remove the API call from the system.
* **Copy call Id**: Copy the unique identifier of the API call.

## Permissions

The only permission for API calls is **Execute**. To use an API call in Workspace, users need the **Execute** permission for it in at least one of their roles.

Grant the **Execute** permission in one of the following ways:

* Share the API call with a role. Refer to [Action menu](#action-menu) for more information.
* In the **Integrations** section of the role permissions, select the API calls that the role can execute, or grant the right to execute all API calls. Refer to [Roles](/user-guide/administration/account-management/roles.md) for more information.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.nexthink.com/configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/api-calls.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.