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-clientThe specification lists
http://127.0.0.1:8000as 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 or disable the API listener |
|
loopback |
Address the HTTP listener binds to: |
|
|
HTTP listener port |
|
|
Number of threads serving HTTP requests |
|
|
Enable the TLS listener |
|
|
Address the TLS listener binds to |
|
|
TLS listener port |
|
Path to the TLS certificate file |
|
|
Path to the TLS certificate key file |
|
|
Path to the |
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}/tokenswith a body containingvalidFor(seconds, required),persistent(defaulttrue),singleUse(allowed only together with"persistent": false), anddescription(up to 127 characters) fields. The expiration time of persistent tokens is capped at 2038-01-19. The token value is returned in thevaluefield, only in the response to this request;GET /v1/users/{user-id}/tokenslists 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 |
|
List all objects accessible to the authenticated user |
POST |
|
Create a new object |
GET |
|
Get details of a specific object |
PATCH |
|
Update common object properties |
DELETE |
|
Delete an object (asynchronous; 204 means the deletion was accepted) |
POST |
|
Get details of up to 500 objects in one request (body: |
POST |
|
Execute an object query |
POST |
|
Search objects by name, address, and other criteria |
GET |
|
Download the log file of the NetXMS agent on a node, as plain text |
POST |
|
Decommission a node: set it to unmanaged and schedule its deletion. Body: |
POST |
|
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 |
|
Start a forced poll of an object (see below) |
GET |
|
Hardware components of a node as stored by the server; |
GET |
|
Software packages of a node as stored by the server; optional |
GET |
|
Physical component tree of a node (ENTITY-MIB), with interface names resolved; |
GET |
|
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 |
|
List active alarms (optional |
GET |
|
Get details of a specific alarm |
POST |
|
Acknowledge an alarm |
POST |
|
Resolve an alarm |
POST |
|
Terminate an alarm |
GET |
|
List comments of an alarm |
POST |
|
Add a comment to an alarm |
GET |
|
List events correlated to an alarm |
Alarm state change operations return status 204 on success.
Incidents
| Method | Endpoint | Description |
|---|---|---|
GET |
|
List incidents |
POST |
|
Create an incident |
GET |
|
Get details of a specific incident |
PUT |
|
Update an incident |
POST |
|
Change incident state |
POST |
|
Assign an incident to a user |
POST |
|
Add a comment to an incident |
POST |
|
Link an alarm to an incident |
DELETE |
|
Unlink an alarm from an incident |
GET |
|
Get incident activity log |
Data Collection
| Method | Endpoint | Description |
|---|---|---|
GET |
|
List DCIs configured on an object |
POST |
|
Create a DCI |
GET, PATCH, DELETE |
|
Get, update, or delete a DCI |
GET |
|
Get current values of all DCIs on an object |
POST |
|
Get current values of up to 500 DCIs on any objects in one request. Body: |
GET |
|
Get historical values of a DCI |
GET |
|
Get the last collected value of a table DCI |
GET |
|
Get DCIs shown in the object’s performance view |
GET |
|
List available agent metrics, tables, and lists |
GET |
|
List available device-driver metrics |
GET |
|
Read the current value of a metric directly from its source, without a DCI (the same as Query… in the DCI editor). Query parameters: |
GET |
|
Read the current value of a table metric directly from its source, without a DCI. Query parameters: |
GET |
|
List the OpenTelemetry metrics received for a node: an array of objects with |
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, ornow) -
timeTo— end time (same formats astimeFrom) -
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, ordaily -
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 |
|
List summary tables or create a new one |
GET, PUT, DELETE |
|
Get, update, or delete a summary table definition |
POST |
|
Query a configured DCI summary table. Body: |
POST |
|
Execute an ad-hoc summary table query from a table definition supplied in the request body |
Log Queries
| Method | Endpoint | Description |
|---|---|---|
GET |
|
List available server logs |
GET |
|
Get details of a specific log |
POST |
|
Query a log using filter definitions |
POST |
|
Query a log using an SQL fragment |
GET |
|
Get a specific log record |
Server Information
| Method | Endpoint | Description |
|---|---|---|
GET |
|
Get server version, build, and configuration details |
GET |
|
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 |
|
HA status; requires no authentication and works on a standby server |
Command Execution
| Method | Endpoint | Description |
|---|---|---|
POST |
|
Execute an agent action on a node |
POST |
|
Execute an NXSL script on an object |
POST |
|
Execute a dashboard script on an object |
POST |
|
Expand macros in text in the context of an object |
POST |
|
Start a remote control (VNC) session to a node |
POST |
|
Enter or leave maintenance mode |
POST |
|
Set object managed or unmanaged state |
POST |
|
Send wake-on-LAN to a node or interface (requires Control access right) |
GET |
|
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 |
|
Send an event, identified by |
POST |
|
Push values to DCIs with Push origin. Body is an array of elements with |
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 |
|
Start an export of DCIs selected by system tag patterns under a root object or by an explicit DCI list; returns |
POST |
|
Preview which metrics an export request would select, without running it |
GET |
|
Get export progress and state (only for the user who started the export) |
GET |
|
Download the archive ( |
Network Data
| Method | Endpoint | Description |
|---|---|---|
GET |
|
ARP cache of a node |
GET |
|
Routing table of a node |
GET |
|
Switch forwarding database (FDB) of a node |
GET |
|
Layer 2, IP, OSPF, or internal communication topology of a node |
GET |
|
MAC address connection history (see Topology) |
GET |
|
Radio interfaces of a node, access point, or wireless domain |
GET |
|
Wireless stations of a node, access point, or wireless domain |
GET |
|
DHCP scopes of a DHCP server node, with address usage counters |
GET |
|
DHCP leases and reservations of a DHCP server node; optional |
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 |
|
List configuration backups of a node |
GET |
|
Get one configuration backup |
POST |
|
Start configuration restore; runs as a background task |
GET |
|
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 |
|
List messages addressed to the authenticated user; optional |
GET |
|
Get a message addressed to the authenticated user |
PUT |
|
Set |
DELETE |
|
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 |
|
List server configuration variables (requires the Edit server configuration variables system access right; hidden variables are never returned) |
GET, PUT, DELETE |
|
Get, set, or delete a server configuration variable |
POST |
|
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 |
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
-
Grafana Integration — using the REST API with Grafana
-
External Tools Integration — connecting external tools to NetXMS