MantisNMS Public API
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/v1prefix. - 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 Customer Portal (portal.mantisops.net) → API keys → Create API key. Account owners and admins can create keys. Set MantisNMS to Read or Write (and the other products to None unless the integration needs them), choose any limits (below), check the Review step, and create the key. Confirming it's you is required. If you grant more than one product, you get one key per product.
The key is shown once. Copy it, then click Run test from here or run the curl command shown to check it works. It can't be shown again. If a key is lost or exposed, revoke it and create a new one. MantisNMS keys begin with mn_live_.
Keys are created only in the Customer Portal. In MantisNMS, Settings → API Keys shows your existing keys and their limits, and you can revoke a key there.
Pass the key in the Authorization header as a Bearer token:
Verify a key and see its scopes with the ping endpoint:
Key limits
You set these when you create a key in the Customer Portal. To change them later, choose Edit limits… in the key's row menu: you can change the companies, allowed IP addresses and expiry; the key itself stays the same. The name and permissions can't be changed: create a new key instead.
| Limit | What it does |
|---|---|
| Expires | 30 days, 90 days (the default), 1 year, a date up to 3 years away, or Never. From the expiry time the key is refused with 401 { "error": "API key expired" }. The key's creator and the account's owners and admins get a reminder email 14 days and 3 days before it expires, and one more after it expires. |
| Allowed IP addresses | Up to 50 IPv4 or IPv6 addresses or CIDR ranges. A call from any other address is refused with 403 { "error": "API key not allowed from this IP address" }. |
| Companies | All companies or Only some. A limited key only sees and changes those companies' sensors and incidents: lists are filtered, a single item outside them returns 404, and acknowledging an incident outside them returns 200 with "acknowledged": false. ping also returns the key's allowedCompanies. One endpoint covers the whole account and can't be split by company: a limited key gets 403 with "code": "company_restricted" from GET /public/v1/sensor-usage. |
The key list in the Portal shows when each key was last used and from which IP address, and warns about keys that have expired, expire within 14 days or have never been used.
Scopes
Each key is granted one of two scopes when created. In the Customer Portal, Read gives read and Write gives read & write.
| 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.
429 + Retry-After when exceeded). CORS is enabled (Access-Control-Allow-Origin: *) so browser apps can call the API with a key.?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: { "error": "Invalid or missing API key" }. |
| 401 | The key has expired: { "error": "API key expired" }. Give it a later expiry with Edit limits in the Portal, or create a new key. |
| 403 | The key is valid but lacks the required scope: { "error": "Insufficient scope: 'write' required" }. |
| 403 | The call came from an address that isn't on the key's allowed IP list: { "error": "API key not allowed from this IP address" }. |
| 403 | A key limited to specific companies called an account-wide endpoint: "code": "company_restricted". |
| 404 | The resource (e.g. a sensor) was not found, or it's outside the companies the key is limited to. |
| 429 | Rate limit exceeded (120 requests / 60 s per key). Wait for the number of seconds in Retry-After. |
Endpoints
Verify an API key and return the tenant it belongs to plus its scopes. Useful as a connection test.
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.
Fetch a single sensor by its id. Returns 404 if no such sensor exists in your tenant.
List incidents (a sensor going down and recovering), most recent first. Add ?state=open to return only currently-open incidents.
Return the billable sensor breakdown for your tenant against your plan — base (non-SNMP) sensors, monitored interfaces, and host aspects.
Acknowledge an active incident. Requires a read & write key. Returns { ok, acknowledged } (acknowledged: false if already acknowledged or not found).
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.
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. |