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: 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, 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). 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 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

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).

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

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

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

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 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

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

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)

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 (metrics.csv, data.csv, manifest.json) for external analysis. The export runs as a background task, can optionally replace object names and metric identifiers with pseudonyms, and is recorded in the audit log.

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)

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)

See Device Configuration Backup.

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. The complete API — including AI assistant, user, event processing policy, notification channel, script library, asset management, and device configuration backup endpoints — is described by the OpenAPI specification in the source repository: src/server/webapi/openapi.yaml.

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)

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