REST API

NetXMS provides a REST API for programmatic access to the monitoring system. The API is served directly from the netxmsd process; resource endpoint paths start with /v1/. It is the primary integration API and is used by the Grafana data source plugin.

All API endpoints use JSON for request and response bodies.

The standalone WebAPI service (nxapisrv) used with older NetXMS versions is deprecated and has been removed; use the built-in web API described on this page.

Built-in Web API

Enabling the API

The HTTP listener, request routing, and the authentication endpoints (/, /v1/login, /v1/logout, /v1/ha/status) are part of the server core and are active by default (Enable defaults to true). Loading the webapi server module adds the resource endpoints (/v1/objects, /v1/alarms, …​). To load the module, add it to netxmsd.conf and restart the server:

Module = webapi

The API listener is configured in the [WEBAPI] section of netxmsd.conf:

Parameter Default Description

Enable

true

Enable or disable the API listener

Address

loopback

Address the HTTP listener binds to. Set to any, *, or an explicit IP address to accept remote connections

Port

8000

HTTP listener port

TLSEnable

false

Enable the TLS listener

TLSAddress

0.0.0.0

Address the TLS listener binds to

TLSPort

8443

TLS listener port

TLSCertificate

Path to the TLS certificate file

TLSCertificateKey

Path to the TLS certificate key file

ReproxyPath

Path to the reproxy executable used for TLS termination
By default the HTTP listener accepts connections on the loopback interface only. For remote clients, set Address in the [WEBAPI] section to any, *, or an explicit IP address.

The listener itself serves plain HTTP. The TLS listener is terminated by an external reproxy process started by the server: it is bundled with the server on Windows, while on Linux reproxy must be installed separately. Alternatively, place a TLS-offloading reverse proxy (nginx, Caddy, Traefik, etc.) in front of the HTTP port.

The base URL for API calls is:

http://<server>:8000/v1/

Authentication

Login

Obtain an authentication token by sending credentials to the login endpoint:

curl -X POST http://server:8000/v1/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "netxms"}'

On success, the server responds with status 201 and a token:

{
  "token": "...",
  "userId": 1,
  "systemAccessRights": 576460752303423487,
  "changePassword": false,
  "graceLogins": 0
}

Login tokens are ephemeral: each use extends the token’s validity by up to 4 hours, up to the absolute lifetime limit set by the WebAPI.AuthTokenMaxLifetime server configuration variable (24 hours by default). The server reports the remaining lifetime in the X-Token-Expires-In response header and sets X-Token-Refresh-Recommended when the token approaches expiration.

Use the token in the Authorization header of subsequent requests:

curl http://server:8000/v1/objects \
  -H "Authorization: Bearer <token>"

To end the session, invalidate the token:

curl -X POST http://server:8000/v1/logout \
  -H "Authorization: Bearer <token>"

Persistent Tokens

For long-lived integrations, issue a persistent token instead of logging in with credentials:

  • In the management client, navigate to Configuration > Users and groups, right-click the user, and select Issue authentication token…​. The dialog lets you set the expiration time and a description.

  • Programmatically, POST /v1/users/{user-id}/tokens with a body containing validFor (seconds, required), persistent (default true), singleUse (allowed only together with "persistent": false), and description (up to 127 characters) fields. The expiration time of persistent tokens is capped at 2038-01-19.

Tokens are issued per user and are not scoped: a token grants the same access as the user account it was issued for. Create a dedicated account with minimal permissions for each integration.

Objects

Method Endpoint Description

GET

/v1/objects

List all objects accessible to the authenticated user

POST

/v1/objects

Create a new object

GET

/v1/objects/{id}

Get details of a specific object

PATCH

/v1/objects/{id}

Update common object properties

POST

/v1/objects/query

Execute an object query

POST

/v1/objects/search

Search objects by name, address, and other criteria

Object queries use NXSL object query scripts, the same as in the management client:

curl -X POST http://server:8000/v1/objects/query \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "type == NODE"}'

Optional body fields include rootObjectId (limit the query to a subtree), fields (additional object attributes to return), orderBy, and limit.

Alarms

Method Endpoint Description

GET

/v1/alarms

List active alarms (optional rootObject query parameter)

GET

/v1/alarms/{id}

Get details of a specific alarm

POST

/v1/alarms/{id}/acknowledge

Acknowledge an alarm

POST

/v1/alarms/{id}/resolve

Resolve an alarm

POST

/v1/alarms/{id}/terminate

Terminate an alarm

GET

/v1/alarms/{id}/comments

List comments of an alarm

POST

/v1/alarms/{id}/comments

Add a comment to an alarm

GET

/v1/alarms/{id}/events

List events correlated to an alarm

Alarm state change operations return status 204 on success.

Incidents

Method Endpoint Description

GET

/v1/incidents

List incidents

POST

/v1/incidents

Create an incident

GET

/v1/incidents/{id}

Get details of a specific incident

PUT

/v1/incidents/{id}

Update an incident

POST

/v1/incidents/{id}/state

Change incident state

POST

/v1/incidents/{id}/assign

Assign an incident to a user

POST

/v1/incidents/{id}/comments

Add a comment to an incident

POST

/v1/incidents/{id}/alarms

Link an alarm to an incident

DELETE

/v1/incidents/{id}/alarms/{alarm-id}

Unlink an alarm from an incident

GET

/v1/incidents/{id}/activity

Get incident activity log

Data Collection

Method Endpoint Description

GET

/v1/objects/{id}/data-collection/configuration

List DCIs configured on an object

GET

/v1/objects/{id}/data-collection/current-values

Get current values of all DCIs on an object

GET

/v1/objects/{id}/data-collection/{dci-id}/history

Get historical values of a DCI

Query parameters for historical data:

  • timeFrom — start time (Unix timestamp, seconds)

  • timeTo — end time (Unix timestamp, seconds)

  • maxRows — maximum number of data points to return

  • maxDataPoints — when set, the server aggregates the response down to at most this many data points

  • tier — storage tier to read from: auto (default), raw, hourly, or daily

  • function — aggregation function to apply when data is aggregated

  • historicalDataType — type of historical data (0=processed, default; 1=raw; 2=raw and processed; 3=full table)

curl "http://server:8000/v1/objects/100/data-collection/200/history?timeFrom=1740000000&timeTo=1740086400&maxRows=1000" \
  -H "Authorization: Bearer <token>"

Summary Tables

Method Endpoint Description

POST

/v1/dci-summary-tables/{id}/query

Query a configured DCI summary table. Body: {"objectId": <root object id>}

POST

/v1/dci-summary-tables/adhoc-query

Execute an ad-hoc summary table query from a table definition supplied in the request body

Log Queries

Method Endpoint Description

GET

/v1/logs

List available server logs

GET

/v1/logs/{log-name}

Get details of a specific log

POST

/v1/logs/{log-name}/query

Query a log using filter definitions

POST

/v1/logs/{log-name}/query-sql

Query a log using an SQL fragment

GET

/v1/logs/{log-name}/records/{id}

Get a specific log record

Server Information

Method Endpoint Description

GET

/v1/server-info

Get server version, build, and configuration details

GET

/v1/status

Lightweight server status for health checks

GET

/v1/ha/status

HA status; requires no authentication and works on a standby server

Command Execution

Method Endpoint Description

POST

/v1/objects/{id}/execute-agent-command

Execute an agent action on a node

POST

/v1/objects/{id}/execute-script

Execute an NXSL script on an object

POST

/v1/objects/{id}/execute-dashboard-script

Execute a dashboard script on an object

POST

/v1/objects/{id}/expand-text

Expand macros in text in the context of an object

POST

/v1/objects/{id}/remote-control

Start a remote control (VNC) session to a node

POST

/v1/objects/{id}/set-maintenance

Enter or leave maintenance mode

POST

/v1/objects/{id}/set-managed

Set object managed or unmanaged state

POST

/v1/objects/{id}/wake-up

Send wake-on-LAN to a node or interface (requires Control access right)

POST

/v1/objects/{id}/take-screenshot

Take a screenshot on a node via the agent
The built-in API has no endpoints for injecting events or pushing DCI values — use the nxevent, nxpush, or nxapush command line tools for those operations.

Error Handling

The API returns standard HTTP status codes:

Code Description

200

Success

201

Resource created

204

Success, no response body

400

Bad request (invalid parameters)

401

Authentication required or token expired

403

Access denied (insufficient permissions)

404

Resource not found

415

Unsupported media type (request body must be JSON)

426

Upgrade required (WebSocket endpoints)

500

Internal server error

503

Service unavailable (returned for most routes on a standby server in an HA setup)

Error responses include a JSON body with the failure reason:

{
  "reason": "Access denied"
}

Failed login attempts may additionally return an errorCode field with details on the failure reason.

Usage Examples

Python — Acknowledge All Critical Alarms

import requests

BASE = "http://server:8000/v1"

# Login
resp = requests.post(f"{BASE}/login",
    json={"username": "admin", "password": "netxms"})
resp.raise_for_status()
headers = {"Authorization": f"Bearer {resp.json()['token']}"}

# Get active alarms and acknowledge critical ones (severity 4)
for alarm in requests.get(f"{BASE}/alarms", headers=headers).json():
    if alarm["severity"] == 4:
        requests.post(f"{BASE}/alarms/{alarm['id']}/acknowledge", headers=headers)
        print(f"Acknowledged alarm {alarm['id']}: {alarm['message']}")

# Logout
requests.post(f"{BASE}/logout", headers=headers)

Bash — Acknowledge All Critical Alarms

#!/bin/bash
API="http://server:8000/v1"

# Login
TOKEN=$(curl -s -X POST "$API/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"netxms"}' | jq -r '.token')

# Get critical alarms and acknowledge them
curl -s "$API/alarms" -H "Authorization: Bearer $TOKEN" | \
  jq -r '.[] | select(.severity == 4) | .id' | \
  while read id; do
    curl -s -X POST "$API/alarms/$id/acknowledge" \
      -H "Authorization: Bearer $TOKEN"
    echo "Acknowledged alarm $id"
  done

# Logout
curl -s -X POST "$API/logout" -H "Authorization: Bearer $TOKEN"

Best Practices

  • Use persistent tokens for automated integrations instead of logging in with credentials

  • Log out when done

  • Avoid polling too frequently; use reasonable intervals (30 seconds or more for dashboards)

  • Create a dedicated user account with minimal permissions for each integration

Next Steps