NSClient++ API#

NSClient++ provides its own HTTP API which can be enabled with the WEBServer module.

The new API is described in separate pages (on per object):


Enable the WEBServer module#

You can enable the WEBServer module during the package installation.


Please ensure to specify a secure password (default).

API WEBServer setup

Alternatively you can enable the WEBServer module on the CLI afterwards:

nscp web install --password <MY SECRET PASSWORD>


Edit the /settings/WEB/server section in the nsclient.ini configuration file. The default values password and allowed hosts (/settings/default) are shared by all modules (i.e. NRPEServer and NSClientServer) if you want to have separate values for the WEBServer you can override them under /settings/WEB/server.

; MODULES - A list of modules.

; WEBServer - A server that listens for incoming HTTP connection and processes incoming requests. It provides both a WEB UI as well as a REST API in addition to simplifying configuration of WEB Server module.
WEBServer = enabled


; PASSWORD - Password used to authenticate against server

; ALLOWED HOSTS - A comaseparated list of allowed hosts. You can use netmasks (/ syntax) or * to create ranges. parent for this key is found under: /settings/default this is marked as advanced in favor of the parent.
allowed hosts =,


; PORT NUMBER - Port to use for WEB server.
port = 8443s

; CERTIFICATE - Ssl certificate to use for the ssl server
certificate = ${certificate-path}/certificate.pem

Restart the nscp service afterwards.

net stop nscp
net start nscp

You can change the password from the command line using the following command:

nscp web password --set icinga

The next chapter provides a quick overview of how you can use the API.



Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

curl -k -i -u admin https://localhost:8443/api/v1/scripts/ext?all=true

In this example, the ext value is provided for the :runtime parameter in the path while true is passed in the query string for the :all parameter. Reserved characters by the HTTP protocol must be URL-encoded as query string, e.g. a space character becomes %20.

For POST, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of 'application/json':

curl -k -i -u admin -X PUT https://localhost:8443/api/v1/modules -d "{\"loaded\":true,\"name\":\"CheckSystem\"}"

Root Endpoint#

You can issue a GET request to the root endpoint to get all the supported versions of the systems. From each version you can further issue a GET to get a list of all endpoint categories that the REST API supports:

curl -k -i -u admin https://localhost:8443/api
curl -k -i -u admin https://localhost:8443/api/v1

Response codes#

The API will return standard HTTP statuses including error codes.

When an error occurs, the response body will sometimes contain additional information about the problem and its source.

2xx: Success#

A status code between 200 and 299 generally means that the request was successful.

4xx: Client Errors#

Authentication failure

Attempting to access a protected resource or using invalid credentials will always result in a 403 Forbidden.

curl -k -i -u nimda https://localhost:8443/api/
HTTP/1.1 403

403 Forbidden

In addition to authentication issues there are two possible types of client errors on API calls that receive request bodies:

Invalid JSON

Sending invalid JSON will result in a 400 Bad Request response.

curl -k -u admin -X PUT https://localhost:8443/api/v1/modules -d "{\"loaded\":true,\"name\":\"
HTTP/1.1 400 Bad Request
Content-Length: 21

Problems parsing JSON

Invalid fields

Sending invalid fields will result in a 422 Unprocessable Entity response. Please note only fields used are read thus sending unused fields will most likely be ignored. Also many times values are only checked for a given value with all other input resulting in a default value.

TODO Add example here.

5xx: Server errors#

A status in the range of 500 generally means that there was a server-side problem and NSClient++ is unable to process your request. The reason for this can be many and the best option to diagnose is to review the NSClient++ log file. In general a 500 should be reported as a bug in the NSClient++ issue tracker: https://github.com/mickem/nscp/issues

HTTP Verbs#

Where possible, the API strives to use appropriate HTTP verbs for each action.

Verb Description
GET Used for retrieving resources.
POST Used for creating resources.
PUT Used for replacing resources or collections.
DELETE Used for deleting resources.

Allowed Hosts#

Ensure to restrict the API to local access, and only allow remote access if necessary.


Keep in mind that the web interface (depending on how it is configured) allows you to modify the client configuration – use with care on remote access!

Edit the /settings/WEB/server section in the nsclient.ini configuration file.


; ALLOWED HOSTS - A commaseparated list of allowed hosts. You can use netmasks (/ syntax) or * to create ranges. parent for this key is found under: /settings/default this is marked as advanced in favor of the parent.
allowed hosts =,

Restart the nscp service afterwards.

net stop nscp
net start nscp


There are two ways to authenticate through the API. Note that most requests (notable exception is static resources) require authentication and will blankly return 403 Forbidden regardless of if the request is valid or not.

Basic Authentication#

curl -k -i -u admin https://localhost:8443/api

Barer token Authentication#

TODO This is not implemented yet (ish).


All resources may have one or more *_url properties linking to other resources. These are meant to provide explicit URLs so that proper API clients don’t need to construct URLs on their own.

TODO This is not implemented yet (ish).

Tips and tricks#

Formatting json#

Since the JSON returned from the APIs are not pretty printed a good idea is to use the python json.tool to make sure the result is readable.

Compare the following two examples:

C:\source\tools>curl -k -u admin https://localhost:8443/api/v1
C:\source\tools>curl -k -u admin https://localhost:8443/api/v1 |python -m json.tool
    "modules_url": "https://localhost:8443/api/v1/modules",
    "queries_url": "https://localhost:8443/api/v1/queries",
    "scripts_url": "https://localhost:8443/api/v1/scripts"

Another option to is to use jq to format the returned JSON output in a readable manner. The documentation prefers python -m json.tool as Python is available nearly everywhere.


Future versions of NSClient++ might set additional fields. Your application should gracefully handle fields it is not familiar with, for example by ignoring them.

Legacy API#

The current stable version of NSClient++ does not yet have the new API which is describe in this page. So for details on that please review the legacy API.

Web Interface#

You can also access the web interface by using your favorite browser.

The Home screen greets you with a metrics overview.

API Home


You can list all (enabled) modules.

API Modules

Each module provides an overview, settings, templates and queries.

API Modules CheckDisk

You can list and select queries provided by this module.

API Modules CheckDisk Queries

Selecting the query jumps to the Queries tab and allows you to run the query immediately.

API Modules CheckDisk Queries check_drivesize


Navigate into the settings tree and modify specific attributes. You need to save changes and reload the service afterwards.

API Settings


Navigate into the queries tree and execute specific commands.

API Queries

API Queries check_drivesize

API Queries check_drivesize Run


This is helpful in case you have trouble with executing checks, or denied remote access.



Save changes after modifications.

API Changes


Reload the NSClient++ service after configuration changes. API Control


Check Plugins#