This is the documentation for the development version. There are no official binaries for it; build it from the source code in git. Download links on these pages work only after the release. For the current release, see version 7.0.

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.

OpenAPI Specification

The complete API is described by an OpenAPI 3 specification in the product source repository: src/server/webapi/openapi.yaml (raw file). The server does not serve it; take it from the source of the same version as your server.

Tools can work from the specification directly:

  • An OpenAPI code generator creates a client library for your language, for example with OpenAPI Generator:

    openapi-generator-cli generate -i openapi.yaml -g python -o netxms-client

    The specification lists http://127.0.0.1:8000 as its server; set the address of your server in the generated client.

  • An LLM-based coding assistant given the specification can write integration code and scripts against the actual endpoints and fields.

  • API tools such as Postman or Swagger UI can import it to browse and try the endpoints.

The tables on this page list the commonly used endpoints; the specification also covers the AI assistant, user, event processing policy, notification channel, script library, asset management, and device configuration backup endpoints.

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: loopback (or localhost), any (or *) for all interfaces, or an explicit IP address

Port

8000

HTTP listener port

ThreadPoolSize

16

Number of threads serving HTTP requests

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, enable the TLS listener, which binds to all interfaces by default (TLSAddress), or put a TLS-offloading reverse proxy in front of the HTTP port. Set Address in the [WEBAPI] section to any, *, or an explicit IP address only when remote clients or a proxy on another host must reach the HTTP listener directly.

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,
  "fullName": "...",
  "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). When less than WebAPI.AuthTokenWarningThreshold seconds (1 hour by default) remain before that limit, responses carry the X-Token-Expires-In header (remaining seconds) and X-Token-Refresh-Recommended: true.

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. The token value is returned in the value field, only in the response to this request; GET /v1/users/{user-id}/tokens lists tokens without their values.

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

DELETE

/v1/objects/{id}

Delete an object (asynchronous; 204 means the deletion was accepted)

POST

/v1/objects/details

Get details of up to 500 objects in one request (body: {"ids": […​]})

POST

/v1/objects/query

Execute an object query

POST

/v1/objects/search

Search objects by name, address, and other criteria

GET

/v1/objects/{id}/agent-log

Download the log file of the NetXMS agent on a node, as plain text

POST

/v1/objects/{id}/decommission

Decommission a node: set it to unmanaged and schedule its deletion. Body: expirationTime (Unix timestamp, ISO 8601 timestamp, or relative time such as +30d; default: now plus Objects.Nodes.DefaultDecommissionExpirationTime days) and clearIpAddresses (default false). Calling it again for a decommissioned node changes the expiration time

POST

/v1/objects/{id}/recommission

Cancel the scheduled deletion of a decommissioned node; the node stays unmanaged and IP addresses cleared during decommissioning are not restored. Returns 409 if the node is not decommissioned

POST

/v1/objects/{id}/poll/{poll-type}

Start a forced poll of an object (see below)

GET

/v1/objects/{id}/hardware-inventory

Hardware components of a node as stored by the server; entries is null if the inventory was never collected

GET

/v1/objects/{id}/software-inventory

Software packages of a node as stored by the server; optional filter query parameter (case-insensitive substring of the package name or description); entries is null if the inventory was never collected

GET

/v1/objects/{id}/physical-components

Physical component tree of a node (ENTITY-MIB), with interface names resolved; timestamp and root are null if the node provides no ENTITY-MIB data

GET

/v1/objects/{id}/user-sessions

User sessions open on a node, read from the agent at request time, with the session agents running in each session. Requires Read agent data access; supported by agents on Windows and Linux

Decommission and recommission apply to nodes only and require Delete access to the node.

For nodes, PATCH accepts primaryName (DNS name or IP address); the primary IP address is derived from it by the configuration poll that the change schedules, and the request fails with 409 if the resolved address is already used by another node or subnet. Object documents include effectiveRights: the caller’s access rights on the object, one boolean attribute per right (for example, read, modify, executeScript).

Node communication settings are grouped into property groups in the object document: polling, snmp, agent, ssh, vnc, modbus, etherNetIp, netconf, and icmp. PATCH and POST /v1/objects accept the same groups; a group in a PATCH request changes only the fields it contains. Credentials (for example, ssh.login, ssh.password, and vnc.password) are returned only to callers with Modify or Read credentials access to the node. A PATCH or POST request with an invalid value in a group (for example, a port outside 1-65535) fails with 400. The node properties mqttProxy, syslogCodepage, and externalGateway are top-level fields, as are webServiceProxy of data collection targets and bindUnderController of a chassis. For a sensor, the modbus group contains only unitId. In POST /v1/objects, bit 0x0100 of creationFlags marks the new node as an external gateway and skips the duplicate IP address check.

The inventory and physical component endpoints return what the last configuration poll stored; start a configuration poll to refresh it.

POST /v1/objects/{id}/poll/{poll-type} starts a poll at once instead of waiting for the schedule. Poll types: status and configuration (most objects), configuration-full (nodes; configuration poll that checks all capabilities again, requires Modify access), interface-names, topology, routing-table, and discovery (nodes), instance-discovery (data collection targets), autobind (objects with automatic binding rules), and map-update (network maps). Other poll types need Read access; an unknown type returns 400 with the valid types in validTypes. By default the response contains a single-use token, wsUrl (/v1/polls/output/{token}), and expiresIn (30 seconds), and the poll starts when a WebSocket connects to wsUrl. Each line of poll output arrives as a text frame {"type":"output","data":"…​"}, with level (info, warning, or error) for highlighted lines; {"type":"completed"} ends the poll and the server closes the connection. If no client connects before the token expires, the poll is cancelled; if the client disconnects, the poll runs to the end without output. With the body {"stream": false} the poll is queued without output and the response has no token.

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.

GET /v1/objects/{id}/agent-log returns the log file of the agent itself as text/plain. It applies to nodes only (400 for other objects), requires the Download files access right on the node, and is recorded in the audit log. The agent must have this server in MasterServers and write its log to a file (LogFile is not {syslog}, {eventlog}, {systemd}, or {stdout}); the file manager subagent is not needed. The optional sizeLimit query parameter limits the response to that many bytes from the end of the file, so its first line is usually incomplete; 0 or no value returns the whole file. On an agent error the response is 500 with agentErrorCode and agentErrorText: 945 means that the agent does not write its log to a file, 403 means that the server is not in the agent’s MasterServers, and 400 means that the agent is too old to support the request.

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

POST

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

Create a DCI

GET, PATCH, DELETE

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

Get, update, or delete a DCI

GET

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

Get current values of all DCIs on an object

POST

/v1/data-collection/current-values

Get current values of up to 500 DCIs on any objects in one request. Body: {"items": [{"objectId": <id>, "dciId": <id>}, …​]}; an item can add both column and instance to select a table DCI cell. Items whose object or DCI is not found or not accessible are listed in errors of the response. Optional delegate (ID of a network map or dashboard the caller can read) serves DCIs it references on objects the caller has only delegated read access to

GET

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

Get historical values of a DCI

GET

/v1/objects/{id}/data-collection/{dci-id}/table-value

Get the last collected value of a table DCI

GET

/v1/objects/{id}/data-collection/performance-view

Get DCIs shown in the object’s performance view

GET

/v1/objects/{id}/data-collection/available-metrics/agent

List available agent metrics, tables, and lists

GET

/v1/objects/{id}/data-collection/available-metrics/device-driver

List available device-driver metrics

GET

/v1/objects/{id}/data-collection/query-metric

Read the current value of a metric directly from its source, without a DCI (the same as Query…​ in the DCI editor). Query parameters: origin and name

GET

/v1/objects/{id}/data-collection/query-table

Read the current value of a table metric directly from its source, without a DCI. Query parameters: origin and name

GET

/v1/objects/{id}/otlp-metrics

List the OpenTelemetry metrics received for a node: an array of objects with name, type, and attributeKeys (attribute names, not values). Requires Read access to the node and the otlp server module (see OpenTelemetry (OTLP) Data Collection)

DCI configuration JSON uses relatedObject for the related object ID. It is returned when reading configuration and can be supplied when creating or updating a DCI.

The available-metrics endpoints require Read access to the object. The agent response contains metrics, tables, and lists arrays; the device-driver response contains a metrics array.

query-metric returns {"value": "…​"}, the value as collected, before any transformation. It supports the origins internal, script, websvc, and trafficobserver on any data collection target, and agent, snmp, driver, smclp, and netconf on nodes. Besides Read access, it requires Read agent data for agent and smclp, Read SNMP data for snmp and driver, Read device configuration for netconf, and Modify for script. An unsupported metric returns 404, a data source error 502, and a failure to reach the data source 503. query-table returns {"table": …​} with the same status codes; it supports the origins internal, script, and trafficobserver on any data collection target, and agent on nodes. Besides Read access, it requires Modify for script and Read agent data for agent.

Current values report the DCI origin, data type, status, and type, and the severity of an active threshold, by name rather than by numeric code, for example "origin": "agent", "dataType": "int32", "status": "active", "type": "item". They also include templateId (the template the DCI comes from; for a DCI created by instance discovery, the DCI owner itself), templateItemId (the template DCI or, for an instance, the prototype DCI), and relatedObject.

Query parameters for historical data:

  • timeFrom — start time (Unix timestamp in seconds, ISO 8601 timestamp, relative offset such as -1d, or now)

  • timeTo — end time (same formats as timeFrom)

  • maxRows — maximum number of data points to return

  • maxDataPoints — when set, the server aggregates the response down to this many data points; the response can have one more, and values above 200000 count as 200000

  • 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

GET, POST

/v1/dci-summary-tables

List summary tables or create a new one

GET, PUT, DELETE

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

Get, update, or delete a summary table definition

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

Status of the current session: user ID, login name, and system access rights. Also full name, GUID, description, email address, phone number, and effective UI access rules

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)

GET

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

Take a screenshot on a node via the agent (returns a PNG image)

Interactive SSH Terminal

Open a terminal with POST /v1/objects/{id}/ssh-terminal, then connect a WebSocket to the returned wsUrl (/v1/ssh-terminal/{token}). The POST requires the Initiate TCP proxy sessions system access right and Control access to the node. The selected SSH proxy agent must have the ssh subagent loaded.

The JSON body requires columns and rows (each 1 to 1024), with optional terminalType. Omit login to use the node’s stored login, password, and SSH key; when login is supplied, optional password and keyId override those credentials.

The response includes token, wsUrl, and expiresIn. The one-use WebSocket token expires after 30 seconds; the WebSocket URL authenticates with that token. Send terminal input as binary frames; output also arrives as binary frames. Resize with a text frame containing {"type":"resize","columns":120,"rows":40}.

Events and Pushed Data

Method Endpoint Description

POST

/v1/events

Send an event, identified by eventCode or eventName, with optional objectId, tags, and parameters. Without objectId, the node with the client’s IP address is the event source. Requires the Send events access right on the source object

POST

/v1/push-data

Push values to DCIs with Push origin. Body is an array of elements with objectId or objectName, dciId or dciName, value, and optional timestamp; the batch is applied completely or not at all. Requires the Push data access right on every target object

Data Export

DCI history can be exported as a ZIP archive for external analysis. It contains the metric catalog (metrics.csv), samples (data.csv), and export metadata (manifest.json). The export runs as a background task, can optionally replace object names and metric identifiers with pseudonyms, and is recorded in the audit log.

metrics.csv also includes delta_method (original, simple, average_per_second, or average_per_minute), transformation (whether a transformation script is configured), and the owner’s time_zone and time_zone_rule when available. manifest.json records SHA-256 digests under files.metrics.sha256 and files.data.sha256, so a consumer can verify the extracted catalog and samples.

The archive also includes objects.csv, with one row per distinct metric owner. It records the owner ID, name, class, and available inventory attributes such as hardware type, vendor, model, serial number, SNMP object ID, platform, OS and agent versions, driver, and hypervisor type; fields that do not apply are empty. In anonymized exports, names use the same pseudonyms as metrics.csv, while object_id and serial_number are empty; the other inventory fields remain. The manifest’s formatVersion is 3, and files.objects.sha256 contains the inventory file’s digest.

Method Endpoint Description

POST

/v1/data-export

Start an export of DCIs selected by system tag patterns under a root object or by an explicit DCI list; returns taskId

POST

/v1/data-export/metrics

Preview which metrics an export request would select, without running it

GET

/v1/data-export/{task-id}

Get export progress and state (only for the user who started the export)

GET

/v1/data-export/{task-id}/file

Download the archive (type=archive, default) or the pseudonym mapping file (type=mapping). Each file can be downloaded once; files are removed one hour after completion

Network Data

Method Endpoint Description

GET

/v1/objects/{id}/arp-cache

ARP cache of a node

GET

/v1/objects/{id}/routing-table

Routing table of a node

GET

/v1/objects/{id}/switch-forwarding-database

Switch forwarding database (FDB) of a node

GET

/v1/objects/{id}/topology/l2, …​/topology/ip, …​/topology/ospf, …​/topology/internal

Layer 2, IP, OSPF, or internal communication topology of a node

GET

/v1/connection-history

MAC address connection history (see Topology)

GET

/v1/objects/{id}/wireless/radios

Radio interfaces of a node, access point, or wireless domain

GET

/v1/objects/{id}/wireless/stations

Wireless stations of a node, access point, or wireless domain

GET

/v1/objects/{id}/dhcp/scopes

DHCP scopes of a DHCP server node, with address usage counters

GET

/v1/objects/{id}/dhcp/leases

DHCP leases and reservations of a DHCP server node; optional scope query parameter limits the result to one scope

The DHCP endpoints require Read access to the node and read the data from the agent or network device driver at request time; on a large DHCP server, query leases per scope. Both return an entries array. A scope has id, network (null if not known), name, ranges, enabled, totalAddresses, usedAddresses, declinedAddresses (null if the DHCP server does not report it), freeAddresses, and utilization (percent of used addresses; null if the scope has no addresses). A lease has ipAddress, prefixLength, scopeId, macAddress, vendor, clientId, hostname, type (DYNAMIC, RESERVATION, or UNKNOWN), state (ACTIVE, EXPIRED, DECLINED, RELEASED, OFFERED, INACTIVE, or UNKNOWN; INACTIVE is a reservation without an active lease), lastTransaction, expiration (null if the lease does not expire or the time is not known), and nodeId and nodeName of the node with the lease’s MAC address (or IP address, if the MAC address is not known). Status codes: 400 if the object is not a node or the node is not a DHCP server, 404 if the object or the requested scope does not exist, 501 if the DHCP server does not provide the requested information, 502 if the data cannot be read, and 503 if the server cannot communicate with the agent.

Device Configuration Backup

Method Endpoint Description

GET

/v1/objects/{id}/device-config-backups

List configuration backups of a node

GET

/v1/objects/{id}/device-config-backups/{backup-id}

Get one configuration backup

POST

/v1/objects/{id}/restore-device-config

Start configuration restore; runs as a background task

GET

/v1/background-tasks/{task-id}

Status of a background task (for example, a configuration restore)

AI Messages

AI messages and approval requests can be accessed through the API.

Method Endpoint Description

GET

/v1/ai/messages

List messages addressed to the authenticated user; optional type and status filters

GET

/v1/ai/messages/{message-id}

Get a message addressed to the authenticated user

PUT

/v1/ai/messages/{message-id}/status

Set status to read, approved, or rejected

DELETE

/v1/ai/messages/{message-id}

Delete a message; requires its initiator or a user with Manage AI tasks rights

The type filter accepts informational, alert, and approvalRequest; status accepts pending, read, approved, and rejected. A message document identifies its creator in origin, an object with type (chat, task, or operator) and id (chat ID, AI task ID, or AI operator ID); origin is null if the creator is not known. Approval and rejection apply to approval requests only. A status change returns the updated message; when approval starts an AI task, the response also has the task ID in spawnedTaskId. Expired messages return 404; an operation that does not apply to the message returns 409.

MCP Endpoint

When the mcp server module is loaded, the same listener serves the Model Context Protocol endpoint /mcp, which gives external AI applications access to the NetXMS AI tools. It accepts the same bearer tokens as the web API and does not need the webapi module. See MCP Endpoint and How to Connect an MCP Client.

User and Group Creation

POST /v1/users and POST /v1/user-groups apply the supplied properties when creating the account or group, rather than only its name. They accept the same configurable properties as the corresponding PUT /v1/users/{id} or PUT /v1/user-groups/{id} operation; the caller needs the Manage users system access right.

SSH Key Import

POST /v1/ssh-keys imports a key when its JSON body contains name and privateKey; the server derives the public key from an unencrypted OpenSSH private key. Without privateKey, it generates a key pair. PUT /v1/ssh-keys/{id} without privateKey renames the key and keeps its key pair. The server ignores publicKey in requests. Invalid names or private keys return 400; updating an unknown key returns 404. Creating or changing keys requires the Manage SSH keys system access right. See SSH Key Management.

Server Configuration

Method Endpoint Description

GET

/v1/server-config

List server configuration variables (requires the Edit server configuration variables system access right; hidden variables are never returned)

GET, PUT, DELETE

/v1/server-config/{name}

Get, set, or delete a server configuration variable

POST

/v1/server-config/{name}/reset

Reset a server configuration variable to its default value

The tables on this page list commonly used endpoints; for the complete API, see OpenAPI Specification.

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

409

Conflict (for example, a name or address is already in use)

415

Unsupported media type (a POST, PUT, or PATCH request with a body must use Content-Type: application/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, and by AI chat endpoints when the AI assistant is not initialized)

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)

Python — Client Wrapper

Scripts that used the Jython-based NXShell of earlier versions are rewritten against the REST API. A small wrapper class keeps them short; the alternative is a client generated from the OpenAPI Specification. The wrapper below uses the requests package and a persistent token (see Persistent Tokens):

import urllib.parse
import requests


class NetXMS:
    """Minimal client for the NetXMS REST API."""

    def __init__(self, url, token, verify=True):
        self.base = url.rstrip("/") + "/v1"
        self.http = requests.Session()
        self.http.headers["Authorization"] = f"Bearer {token}"
        self.http.verify = verify

    def call(self, method, path, **kwargs):
        response = self.http.request(method, self.base + path, timeout=60, **kwargs)
        response.raise_for_status()
        return response.json() if response.content else None

    def find_object(self, name):
        # The search matches parts of names and aliases; keep exact name matches only
        found = [o for o in self.call("POST", "/objects/search", json={"name": name})
                 if o["name"].casefold() == name.casefold()]
        if len(found) != 1:
            raise LookupError(f"{len(found)} objects named {name!r}")
        return found[0]

    def rename(self, object_id, new_name):
        return self.call("PATCH", f"/objects/{object_id}", json={"name": new_name})

    def set_custom_attribute(self, object_id, name, value, inheritable=False):
        path = f"/objects/{object_id}/custom-attributes/{urllib.parse.quote(name, safe='')}"
        return self.call("PUT", path, json={"value": value, "inheritable": inheritable})

    def find_dci(self, object_id, metric):
        found = [d for d in self.call("GET", f"/objects/{object_id}/data-collection/configuration")
                 if d["name"] == metric]
        if len(found) != 1:
            raise LookupError(f"{len(found)} DCIs with metric {metric!r}")
        return found[0]

    def history(self, object_id, dci_id, time_from, time_to):
        # Collected values (not hourly or daily aggregates), newest first, at most 200000
        params = {"timeFrom": int(time_from), "timeTo": int(time_to), "tier": "raw", "maxRows": 200000}
        return self.call("GET", f"/objects/{object_id}/data-collection/{dci_id}/history",
                         params=params)["values"]

    def alarms(self):
        return self.call("GET", "/alarms")

    def terminate_alarm(self, alarm_id):
        self.call("POST", f"/alarms/{alarm_id}/terminate")

    def execute_script(self, object_id, script, *parameters):
        # Returns the script's return value; output of println() is not returned
        body = {"script": script, "parameters": [str(p) for p in parameters]}
        return self.call("POST", f"/objects/{object_id}/execute-script", json=body)["result"]

Tasks that old NXShell scripts did, with the wrapper:

import csv
import os
import time
from datetime import datetime, timedelta, timezone

nx = NetXMS("https://netxms.example.com:8443", os.environ["NETXMS_TOKEN"])

# Export one week of CPU usage of server01 to CSV, oldest value first
node = nx.find_object("server01")
dci = nx.find_dci(node["id"], "System.CPU.Usage")
now = time.time()
with open("cpu.csv", "w", newline="") as f:
    writer = csv.writer(f)
    writer.writerow(["timestamp", "value"])
    for v in reversed(nx.history(node["id"], dci["id"], now - 7 * 86400, now)):
        writer.writerow([v["timestamp"], v["value"]])

# Set custom attributes from a CSV file with columns node_name, location
with open("locations.csv", newline="") as f:
    for row in csv.DictReader(f):
        nx.set_custom_attribute(nx.find_object(row["node_name"])["id"], "location", row["location"])

# Terminate alarms that have not changed for 30 days
limit = datetime.now(timezone.utc) - timedelta(days=30)
for alarm in nx.alarms():
    if datetime.fromisoformat(alarm["lastChangeTime"].replace("Z", "+00:00")) < limit:
        nx.terminate_alarm(alarm["id"])

# Run NXSL on the node
print(nx.execute_script(node["id"], "return $node.interfaces.size;"))

Each call needs the access rights of the token’s user for that operation: for example Modify for renaming an object or setting a custom attribute, Terminate alarms for terminating an alarm, and Execute scripts for running NXSL on an object.

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