Skip to content

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 group
  • type: required - should be static or dynamic. Setting this to static requires that the devices input be provided
  • desc: optional - Description of the device group
  • rules: required if type == dynamic - A set of rules to determine which devices should be included in this device group
  • devices: 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"
}
Back to top