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

The API uses personal API tokens. A token acts as you — its access is the intersection of your own permissions and sites with whatever scope the token was minted with, so it can never reach more than your account can, and can be narrowed to reach less (see Scoping a token below).

Create a token:

1. Open Profile → API Tokens (your avatar, top-right — see Your Account).
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:

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

Revoke a token any time from the same Profile → API Tokens screen — revocation, and any change to your own role, takes effect on the very next request.

Note

For security, a token can’t create more tokens — new tokens must be created from a logged-in browser session.

Scoping a token

By default a new token inherits your full account access. You can narrow it at creation time:

• Read-only — a convenience preset that limits the token to read access across every resource. Pass "readOnly": true.
• A custom scope — a scopePerms map naming exactly which resources the token may use and for which actions (read, write, delete), for example {"devices": ["read"], "events": ["read", "write"]}. An explicit scopePerms always wins over readOnly rather than combining with it.
• Site restriction — a scopeSites list of site IDs. Omit it to inherit every site your account can already see.

GET /api/v1/tokens/scope-options returns the current list of valid resource names and actions, so you can build a picker instead of hardcoding the vocabulary:

curl -H "Authorization: Bearer $GNMS_TOKEN" \
  https://app.gridnms.io/api/v1/tokens/scope-options
# → { "success": true, "data": { "resources": ["devices","events",…], "actions": ["read","write","delete"] } }

Create a read-only token, from a script running as a logged-in session:

curl -X POST -H "Content-Type: application/json" \
  -d '{"name":"reporting-bot","readOnly":true}' \
  https://app.gridnms.io/api/v1/tokens

Create a token scoped to just device reads on two sites:

curl -X POST -H "Content-Type: application/json" \
  -d '{"name":"device-dashboard","scopePerms":{"devices":["read"]},"scopeSites":[12,15]}' \
  https://app.gridnms.io/api/v1/tokens

A request outside a token’s scope is rejected with 403 { "success": false, "code": "token_scope_denied" } — distinguishable from an ordinary permission 403, so your integration can tell “this token isn’t allowed to do that” apart from “your account role can’t do that.”

Base URL & conventions

• Base URL: https://app.gridnms.io (self-hosted: your own instance host).
• Path prefix: /api/v1 is the canonical, versioned prefix — use it for all new integrations. The unversioned /api prefix is a permanent alias: every endpoint below is reachable identically under either prefix, and always will be.
• 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 either your account lacks permission (or site access) for that resource, or the token’s own scope doesn’t cover it (see code: "token_scope_denied" above); a 404 means the resource doesn’t exist or isn’t visible to you; a 400 means a query parameter is invalid or not recognized.

Endpoints

The stable, customer-facing read endpoints (shown at the versioned /api/v1 prefix — the unversioned /api prefix works identically):

Method & path	What it does
GET /api/v1/devices	List devices (filters: search, Address, monitor, class, collector, page, pageSize).
GET /api/v1/devices/{id}	Get one device.
GET /api/v1/events	List events (filters: from, to, Severity, Source, Device, Tag, Message, Name, SenderHost, hideCaseManaged, sort, dir, page, pageSize). Filter names are case-sensitive; any other query parameter is rejected with 400.
GET /api/v1/events/{id}	Get one event.
GET /api/v1/cases	List cases (filters: status, severity, priority, assignee, tag, q, page, pageSize).
GET /api/v1/cases/{id}	Get one case with its events and activity.
GET /api/v1/interfaces?deviceId={id}	List a device’s interfaces (deviceId is required).
GET /api/v1/tokens	List your API tokens (metadata only, never the secret).
POST /api/v1/tokens	Create a token. Body: { "name": "…", "readOnly"?, "scopePerms"?, "scopeSites"? } — see Scoping a token. Returns the plaintext token once.
DELETE /api/v1/tokens/{id}	Revoke one of your tokens.
GET /api/v1/tokens/scope-options	List the resources and actions a token’s scopePerms may name.

Examples

List monitored devices:

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

Get a single device:

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

Events from the last hour, minor severity or worse:

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

List cases that are still open:

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

List a device’s interfaces:

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

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.
• Events are immutable — an event is a point-in-time record of something that happened, with no open/acknowledged/closed status of its own. The ongoing investigation lifecycle lives on Cases instead; an event that’s been triaged shows InCase/CaseId pointing at the case handling it.
• Case status: 0 open, 1 investigating, 2 resolved, 3 closed.

See Severity & Status Codes for the full reference.

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.

Note

The API evolves with each release, and the running instance is the source of truth. Building a substantial integration? Reach out to support@gridnms.io — we’re happy to help.