Skip to content
GridNMS Docs

REST API Reference

Everything you do in the GridNMS web app is backed by a REST API, so you can script bulk operations, build reports, or wire GridNMS into your own systems.

Authentication

Section titled “Authentication”

The API uses personal API tokens. A token acts as you — it inherits your permissions and the sites you can see, so it can only reach what your account can.

Create a token:

  1. Open Profile → API Tokens.
  2. Give it a name and create it.
  3. Copy the token — it starts with gnms_ and is shown only once. Store it somewhere safe (a secret manager, a CI secret). If you lose it, revoke it and make a new one.

Use it by sending it as a Bearer token on every request:

Terminal window
export GNMS_TOKEN="gnms_your_token_here"
curl -H "Authorization: Bearer $GNMS_TOKEN" https://app.gridnms.io/api/devices

Revoke a token any time from the same Profile → API Tokens screen — revocation takes effect immediately.

Base URL & conventions

Section titled “Base URL & conventions”
  • Base URL: https://app.gridnms.io (self-hosted: your own instance host). All endpoints live under /api.
  • Response envelope: every response is JSON in the shape { "success": true, "data": … }. List endpoints also return a totalCount (or total) for pagination.
  • Pagination: list endpoints take page (1-based, default 1) and pageSize (default 25).
  • Timestamps are Unix seconds (integers).
  • Errors: a 401 means your token is missing or invalid; a 403 means the token is valid but your account lacks permission (or site access) for that resource; a 404 means the resource doesn’t exist or isn’t visible to you.

Endpoints

Section titled “Endpoints”

The stable, customer-facing read endpoints:

Method & path What it does
GET /api/devices List devices (filters: search, Address, monitor, class, collector, page, pageSize).
GET /api/devices/{id} Get one device.
GET /api/events List events (filters: from, to, Severity, Status, Source, Device, page, pageSize).
GET /api/events/{id} Get one event.
GET /api/cases List cases (filters: status, severity, priority, assignee, tag, q, page, pageSize).
GET /api/cases/{id} Get one case with its events and activity.
GET /api/interfaces?deviceId={id} List a device’s interfaces (deviceId is required).
POST /api/discovery/scan Start a network scan. Body: { "targets": "10.0.20.0/24", "profile": "medium" }. Returns a scanId.
GET /api/tokens List your API tokens (metadata only, never the secret).
POST /api/tokens Create a token. Body: { "name": "…" }. Returns the plaintext token once.
DELETE /api/tokens/{id} Revoke one of your tokens.

Examples

Section titled “Examples”

List monitored devices:

Terminal window
curl -H "Authorization: Bearer $GNMS_TOKEN" \
  "https://app.gridnms.io/api/devices?monitor=1&pageSize=50"

Get a single device:

Terminal window
curl -H "Authorization: Bearer $GNMS_TOKEN" \
  https://app.gridnms.io/api/devices/42

Open events from the last hour, minor severity or worse:

Terminal window
FROM=$(($(date +%s) - 3600))
curl -H "Authorization: Bearer $GNMS_TOKEN" \
  "https://app.gridnms.io/api/events?from=$FROM&Severity=3&Status=0"

List cases that are still open:

Terminal window
curl -H "Authorization: Bearer $GNMS_TOKEN" \
  "https://app.gridnms.io/api/cases?status=0,1"

List a device’s interfaces:

Terminal window
curl -H "Authorization: Bearer $GNMS_TOKEN" \
  "https://app.gridnms.io/api/interfaces?deviceId=42"

Kick off a discovery scan:

Terminal window
curl -X POST -H "Authorization: Bearer $GNMS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"targets":"10.0.20.0/24","profile":"medium"}' \
  https://app.gridnms.io/api/discovery/scan

Create a token (from a script running as a logged-in session):

Terminal window
curl -X POST -H "Content-Type: application/json" \
  -d '{"name":"reporting-bot"}' \
  https://app.gridnms.io/api/tokens
# → { "success": true, "token": "gnms_…", "data": { … } }

Severity & status codes

Section titled “Severity & status codes”

Several endpoints use numeric codes:

  • Severity: 1 critical, 2 major, 3 minor, 4 warning, 5 info. Event filters treat Severity as an inclusive ceiling — Severity=3 returns critical, major, and minor.
  • Event status: 0 open, 1 acknowledged, 2 closed.
  • Case status: 0 open, 1 investigating, 2 resolved, 3 closed.

See Severity & Status Codes for the full reference.

Machine-readable spec

Section titled “Machine-readable spec”

A full OpenAPI 3.1 description of the API is served at:

https://app.gridnms.io/api/openapi.json

Import it into Postman, Insomnia, or any OpenAPI tool to get an auto-generated client and request collection.