MantisNMS Public API

MantisNMS · API v1 · Base URL https://api.nms.mantisops.net

The MantisNMS Public API is a simple REST/JSON interface for reading your monitored sensors and their live state, incidents, and sensor usage programmatically — for dashboards, SIEM/ticketing integrations, status pages, and reporting. Every request is authenticated with an API key and scoped to the tenant that issued it.

Overview

Base URL: https://api.nms.mantisops.net
Version: all endpoints are under the /public/v1 prefix.
Format: JSON request and response bodies; UTF-8.
Auth: a Bearer API key on every request (below).
Tenancy: a key only ever sees data for the tenant that created it.

Authentication

Create keys in the MantisNMS app under Settings → API Keys. A key is displayed once at creation — store it securely; it cannot be retrieved again. If a key is lost or exposed, revoke it and issue a new one. MantisNMS keys begin with mn_live_.

Pass the key in the Authorization header as a Bearer token:

curl https://api.nms.mantisops.net/public/v1/sensors \
  -H "Authorization: Bearer mn_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Verify a key and see its scopes with the ping endpoint:

curl https://api.nms.mantisops.net/public/v1/ping \
  -H "Authorization: Bearer mn_live_..."

{ "ok": true, "product": "nms", "version": "v1",
  "tenant": "t_abc123", "scopes": ["read"] }

⚠

Keys are stored only as a hash. MantisOps cannot recover a key for you — if it's lost, revoke it and create a new one. Treat keys like passwords and never commit them to source control.

Scopes

Each key is granted one of two scopes when created:

Scope	Grants
read	All `GET` endpoints — list and read sensors, incidents, and usage.
read & write	Everything `read` allows, plus write endpoints — currently `POST /public/v1/incidents/{id}/acknowledge` and `PATCH /public/v1/sensors/{id}`.

A request to a write endpoint with a read-only key returns 403. Grant the narrowest scope an integration needs.

ℹ

Rate limit: 120 requests / 60 s per key (429 + Retry-After when exceeded). CORS is enabled (Access-Control-Allow-Origin: *) so browser apps can call the API with a key.

ℹ

Pagination: list endpoints accept ?limit=N&offset=M (limit capped at 1000). Omit limit to receive the full list (default — unchanged behavior). List responses include limit, offset, hasMore, and (on most endpoints) total alongside the items — page by incrementing offset until hasMore is false.

Errors

Errors use standard HTTP status codes and a JSON body of the form { "error": "message" }.

Status	Meaning
400	Malformed request (e.g. a required field is missing).
401	Missing, malformed, revoked, or unknown API key.
403	The key is valid but lacks the required scope.
404	The resource (e.g. a sensor) was not found.

Endpoints

GET/public/v1/pingread

Verify an API key and return the tenant it belongs to plus its scopes. Useful as a connection test.

curl https://api.nms.mantisops.net/public/v1/ping \
  -H "Authorization: Bearer mn_live_..."

200 OK
{ "ok": true, "product": "nms", "version": "v1",
  "tenant": "t_abc123", "scopes": ["read"] }

GET/public/v1/sensorsread

List every sensor in your tenant with its current state. Returns an array of sensor objects and a total count. Add ?companyId=<id> to return only sensors for one company.

curl "https://api.nms.mantisops.net/public/v1/sensors?companyId=co_1a2b" \
  -H "Authorization: Bearer mn_live_..."

200 OK
{
  "count": 2,
  "sensors": [
    {
      "id": "sn_9f2c...", "name": "Core switch uplink", "type": "snmp",
      "target": "10.0.0.1", "enabled": true, "intervalSec": 60,
      "state": "up", "latencyMs": 3.2, "httpStatus": null,
      "certDaysLeft": null, "lastCheckedAt": 1751990400000,
      "tags": ["core", "uplinks"], "companyId": "co_1a2b"
    }
  ]
}

GET/public/v1/sensors/{id}read

Fetch a single sensor by its id. Returns 404 if no such sensor exists in your tenant.

curl https://api.nms.mantisops.net/public/v1/sensors/sn_9f2c... \
  -H "Authorization: Bearer mn_live_..."

200 OK
{ "id": "sn_9f2c...", "name": "Core switch uplink", "type": "snmp",
  "target": "10.0.0.1", "state": "up", "latencyMs": 3.2,
  "lastCheckedAt": 1751990400000, "tags": ["core"] }

GET/public/v1/incidentsread

List incidents (a sensor going down and recovering), most recent first. Add ?state=open to return only currently-open incidents.

curl "https://api.nms.mantisops.net/public/v1/incidents?state=open" \
  -H "Authorization: Bearer mn_live_..."

200 OK
{
  "count": 1,
  "incidents": [
    {
      "id": "in_5d1e...", "sensorId": "sn_9f2c...",
      "sensorName": "Core switch uplink", "cause": "Interface Gi1/0/1 down",
      "openedAt": 1751990100000, "closedAt": null, "open": true
    }
  ]
}

GET/public/v1/sensor-usageread

Return the billable sensor breakdown for your tenant against your plan — base (non-SNMP) sensors, monitored interfaces, and host aspects.

curl https://api.nms.mantisops.net/public/v1/sensor-usage \
  -H "Authorization: Bearer mn_live_..."

200 OK
{ "baseSensors": 4, "interfaceSensors": 12, "hostSensors": 6,
  "total": 22, "limit": 100, "remaining": 78 }

POST/public/v1/incidents/{id}/acknowledgewrite

Acknowledge an active incident. Requires a read & write key. Returns { ok, acknowledged } (acknowledged: false if already acknowledged or not found).

curl -X POST https://api.nms.mantisops.net/public/v1/incidents/in_.../acknowledge \
  -H "Authorization: Bearer mn_live_..."

200 OK
{ "ok": true, "acknowledged": true }

PATCH/public/v1/sensors/{id}write

Update a sensor. Requires a read & write key. Body may include enabled (boolean), name (string), and intervalSec (number, ≥ 30). Targets and SNMP credentials stay app-managed. Returns 404 if the sensor doesn't exist in your tenant.

curl -X PATCH https://api.nms.mantisops.net/public/v1/sensors/sn_... \
  -H "Authorization: Bearer mn_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false, "intervalSec": 120 }'

200 OK
{ "ok": true, "id": "sn_..." }

Sensor object

Fields returned for a sensor. Optional fields are null when not applicable (e.g. httpStatus only for HTTP sensors). SNMP community strings and v3 credentials are never returned.

Field	Type	Description
id	string	Unique sensor identifier.
name	string	Sensor name.
type	string	`snmp`, `icmp`, `http`, `tls`, or `tcp`.
target	string	Host, host:port, or URL being monitored.
enabled	boolean	Whether the sensor is actively polled.
intervalSec	number	Poll interval in seconds.
state	string	Current state: `up` or `down` (null until first check).
latencyMs	number	Last measured latency in milliseconds.
httpStatus	number	Last HTTP status code (HTTP sensors).
certDaysLeft	number	Days until the TLS certificate expires (TLS/HTTPS sensors).
lastCheckedAt / stateSince	number	Last check time, and when the current state began (Unix epoch ms).
tags	string[]	Operator-assigned tags.
companyId / collectorId	string	Company placement + the collector that polls it.
createdAt	number	When the sensor was created (Unix epoch ms).

Incident object

Fields returned for an incident.

Field	Type	Description
id	string	Unique incident identifier.
sensorId / sensorName	string	The affected sensor.
cause	string	Why the incident opened (e.g. `Interface Gi1/0/1 down`).
openedAt	number	When the incident opened (Unix epoch ms).
closedAt	number	When it recovered, or `null` if still open (Unix epoch ms).
open	boolean	`true` while the incident is unresolved.

💡

More endpoints are on the roadmap. Need one that isn't here yet? Let us know.