API Overview

The REST API is served by the same process that serves the UI, under /api (for example https://<your-host>:3001/api). All routes require session authentication except the setup and auth endpoints.

Authentication

GridNMS uses session-based authentication with passkey (WebAuthn) support. Sign in through the UI; the browser session cookie authorizes subsequent API calls. Role-based access control is enforced per route — every endpoint checks the caller’s permissions.

Resource map

Prefix	Resource
/api/devices	Device inventory CRUD, search, state
/api/events	Live events — list, bulk actions, histogram
/api/events/history	Archived events — search with date range, histogram
/api/vlans	VLANs and interface assignments
/api/interfaces	Device interface data, bandwidth metrics, thresholds
/api/neighbors	CDP/LLDP neighbor relationships
/api/nodes	MAC/IP endpoint nodes
/api/topology	Nodes + edges for the topology map
/api/packs	Pack definitions, collectors, views, thresholds, metrics
/api/pack-collector-overrides	Per-device / per-class collector enable/disable
/api/classes	Device class hierarchy
/api/roles	Role definitions with permission matrices
/api/groups	Group management (role assignment)
/api/mibs	MIB upload, OID tree browser, live SNMP query
/api/subscriptions	Per-user event subscriptions
/api/transformations	Event transformation rules
/api/notification-endpoints	Notification endpoint CRUD and delivery queue
/api/maintenance	Maintenance windows
/api/users	User management
/api/reports	Inventory and event-summary reports
/api/dashboard	Dashboard portlet data
/api/problems	Open events aggregated by device
/api/search	Global search
/api/history	Device change audit log
/api/discovery	Network scan (SSE progress), enrichment, bulk save
/api/setup	First-run wizard

Note

The API surface evolves with each release. The table above lists the primary resource areas; the running instance is the source of truth for exact request and response shapes.