DeviceGroups
get_devicegroups
List all device groups.
Route: /api/v0/devicegroups
Input (JSON):
-
Examples:
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devicegroups
Output:
[
{
"status": "ok",
"message": "Found 1 device groups",
"count": 1,
"groups": [
{
"id": "1",
"name": "Testing",
"desc": "Testing",
"pattern": "%devices.status = \"1\" &&"
}
]
}
]
add_devicegroup
Add a new device group. Upon success, the ID of the new device group is returned
and the HTTP response code is 201
.
Route: /api/v0/devicegroups
Input (JSON):
name
: required - The name of the device grouptype
: required - should bestatic
ordynamic
. Setting this to static requires that the devices input be provideddesc
: optional - Description of the device grouprules
: required if type == dynamic - A set of rules to determine which devices should be included in this device groupdevices
: required if type == static - A list of devices that should be included in this group. This is a static list of devices
Examples:
Dynamic Example:
curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
-X POST https://librenms.org/api/v0/devicegroups \
--data-raw '
{
"name": "New Device Group",
"desc": "A very fancy dynamic group",
"type": "dynamic",
"rules": "{\"condition\":\"AND\",\"rules\":[{\"id\":\"access_points.name\",\"field\":\"access_points.name\",\"type\":\"string\",\"input\":\"text\",\"operator\":\"equal\",\"value\":\"accesspoint1\"}],\"valid\":true}"
}
'
Output:
{
"status": "ok",
"id": 86,
"message": "Device group New Device Group created"
}
Static Example:
curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
-X POST https://librenms.org/api/v0/devicegroups \
-d '{"name":"New Device Group","type":"static","devices":[261,271]}'
Output:
{
"status": "ok",
"id": 86,
"message": "Device group New Device Group created"
}
get_devices_by_group
List all devices matching the group provided.
Route: /api/v0/devicegroups/:name
- name Is the name of the device group which can be obtained using
get_devicegroups
. Please ensure that the name is urlencoded if it needs to be (i.e Linux Servers would need to be urlencoded.
Input (JSON):
- full: set to any value to return all data for the devices in a given group
Examples:
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devicegroups/LinuxServers
Output:
[
{
"status": "ok",
"message": "Found 3 in group LinuxServers",
"count": 3,
"devices": [
{
"device_id": "15"
},
{
"device_id": "18"
},
{
"device_id": "20"
}
]
}
]
maintenance_devicegroup
Set a device group into maintenance mode.
Route: /api/v0/devicesgroups/:name/maintenance
Input (JSON):
- title: Some title for the Maintenance
- notes: Some description for the Maintenance
- start: Start time of Maintenance in format H:m
- duration: Duration of Maintenance in format H:m
Example:
curl -X POST -d '{"title":"Device group Maintenance","notes":"A 2 hour Maintenance triggered via API","start":"04:30","duration":"2:00"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/localhost/maintenance
Output:
{
"status": "ok",
"message": "Device group Cisco switches (2) will begin maintenance mode at 5:00 for 2:00 h"
}