Skip to content

Devices

del_device

Delete a given device.

Route: /api/v0/devices/:hostname

  • hostname can be either the device hostname or id

Input:

-

Example:

curl -X DELETE -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost

Output:

{
    "status": "ok",
    "message": "Removed device localhost",
    "devices": [
        {
            "device_id": "1",
            "hostname": "localhost",
            ...
            "serial": null,
            "icon": null
        }
    ]
}

get_device

Get details of a given device.

Route: /api/v0/devices/:hostname

  • hostname can be either the device hostname or id

Input:

-

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost

Output:

{
    "status": "ok",
    "devices": [
        {
            "device_id": "1",
            "hostname": "localhost",
            ...
            "serial": null,
            "icon": null
        }
    ]
}

discover_device

Trigger a discovery of given device.

Route: /api/v0/devices/:hostname/discover

  • hostname can be either the device hostname or id

Input:

-

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/discover

Output:

{
    "status": "ok",
    "result": {
        "status": 0,
        "message": "Device will be rediscovered"
    },
    "count": 2
}

availability

Get calculated availabilities of given device.

Route: /api/v0/devices/:hostname/availability

  • hostname can be either the device hostname or id

Input:

-

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/availability

Output:

{
    "status": "ok",
    "availability": [
        {
            "duration": 86400,
            "availability_perc": "100.000000"
        },
        {
            "duration": 604800,
            "availability_perc": "100.000000"
        },
        {
            "duration": 2592000,
            "availability_perc": "99.946000"
        },
        {
            "duration": 31536000,
            "availability_perc": "99.994000"
        }
    ],
    "count": 4
}

outages

Get detected outages of given device.

Route: /api/v0/devices/:hostname/outages

  • hostname can be either the device hostname or id

Input:

-

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/outages

Output:

{
    "status": "ok",
    "outages": [
        {
            "going_down": 1593194031,
            "up_again": 1593194388
        },
        {
            "going_down": 1593946507,
            "up_again": 1593946863
        },
        {
            "going_down": 1594628616,
            "up_again": 1594628968
        },
        {
            "going_down": 1594628974,
            "up_again": 1594629339
        },
        {
            "going_down": 1594638668,
            "up_again": 1594638992
        }
    ],
    "count": 5
}

get_graphs

Get a list of available graphs for a device, this does not include ports.

Route: /api/v0/devices/:hostname/graphs

  • hostname can be either the device hostname or id

Input:

-

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/graphs

Output:

{
    "status": "ok",
    "message": "",
    "count": 3,
    "graphs": [
        {
            "desc": "Poller Time",
            "name": "device_poller_perf"
        },
        {
            "desc": "Ping Response",
            "name": "device_ping_perf"
        },
        {
            "desc": "System Uptime",
            "name": "uptime"
        }
    ]
}

list_available_health_graphs

This function allows to do three things:

  • Get a list of overall health graphs available.
  • Get a list of health graphs based on provided class.
  • Get the health sensors information based on ID.

Route: /api/v0/devices/:hostname/health(/:type)(/:sensor_id)

  • hostname can be either the device hostname or id
  • type (optional) is health type / sensor class
  • sensor_id (optional) is the sensor id to retrieve specific information.

Input:

-

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/health

Output:

{
    "status": "ok",
    "message": "",
    "count": 2,
    "graphs": [
        {
            "desc": "Airflow",
            "name": "device_airflow"
        },
        {
            "desc": "Voltage",
            "name": "device_voltage"
        }
    ]
}

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/health/device_voltage

Output:

{
    "status": "ok",
    "message": "",
    "count": 2,
    "graphs": [
        {
            "sensor_id": "1",
            "desc": "Input Feed A"
        },
        {
            "sensor_id": "2",
            "desc": "Output Feed"
        }
    ]
}

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/health/device_voltage/1

Output:

{
    "status": "ok",
    "message": "",
    "count": 1,
    "graphs": [
        {
            "sensor_id": "1",
            "sensor_deleted": "0",
            "sensor_class": "voltage",
            "device_id": "1",
            "poller_type": "snmp",
            "sensor_oid": ".1.3.6.1.4.1.318.1.1.27.1.1.0",
            "sensor_index": "1",
            "sensor_type": "apc",
            "sensor_descr": "Input",
            "sensor_divisor": "1",
            "sensor_multiplier": "1",
            "sensor_current": "1",
            "sensor_limit": "1.15",
            "sensor_limit_warn": null,
            "sensor_limit_low": "0.85",
            "sensor_limit_low_warn": null,
            "sensor_alert": "1",
            "sensor_custom": "No",
            "entPhysicalIndex": null,
            "entPhysicalIndex_measured": null,
            "lastupdate": "2017-01-13 13:50:26",
            "sensor_prev": "1"
        }
    ]
}

list_available_wireless_graphs

This function allows to do three things:

  • Get a list of overall wireless graphs available.
  • Get a list of wireless graphs based on provided class.
  • Get the wireless sensors information based on ID.

Route: /api/v0/devices/:hostname/wireless(/:type)(/:sensor_id)

  • hostname can be either the device hostname or id
  • type (optional) is wireless type / wireless class
  • sensor_id (optional) is the sensor id to retrieve specific information.

Input:

-

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/wireless

Output:

{
    "status": "ok",
    "graphs": [
        {
            "desc": "Ccq",
            "name": "device_wireless_ccq"
        },
        {
            "desc": "Clients",
            "name": "device_wireless_clients"
        }
    ],
    "count": 2
}

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/wireless/device_wireless_ccq

Output:

{
    "status": "ok",
    "graphs": [
        {
            "sensor_id": "791",
            "desc": "SSID: bast (ng)"
        },
        {
            "sensor_id": "792",
            "desc": "SSID: bast (na)"
        }
    ],
    "count": 2
}

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/health/device_wireless_ccq/1

Output:

{
    "status": "ok",
    "graphs": [
        {
            "sensor_id": "791",
            "sensor_deleted": "0",
            "sensor_class": "ccq",
            "device_id": "381",
            "sensor_index": "0",
            "sensor_type": "unifi",
            "sensor_descr": "SSID: bast (ng)",
            "sensor_divisor": "10",
            "sensor_multiplier": "1",
            "sensor_aggregator": "sum",
            "sensor_current": "100",
            "sensor_prev": "100",
            "sensor_limit": null,
            "sensor_limit_warn": null,
            "sensor_limit_low": null,
            "sensor_limit_low_warn": null,
            "sensor_alert": "1",
            "sensor_custom": "No",
            "entPhysicalIndex": null,
            "entPhysicalIndex_measured": null,
            "lastupdate": "2017-12-06 21:26:29",
            "sensor_oids": "[\".1.3.6.1.4.1.41112.1.6.1.2.1.3.0\"]",
            "access_point_id": null
        }
    ],
    "count": 1
}

get_health_graph

Get a particular health class graph for a device, if you provide a sensor_id as well then a single sensor graph will be provided. If no sensor_id value is provided then you will be sent a stacked sensor graph.

Route: /api/v0/devices/:hostname/graphs/health/:type(/:sensor_id)

  • hostname can be either the device hostname or id
  • type is the name of the health graph as returned by list_available_health_graphs
  • sensor_id (optional) restricts the graph to return a particular health sensor graph.

Input:

-

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/graphs/health/device_voltage

Output:

Output is a stacked graph for the health type provided.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/graphs/health/device_voltage/1

Output:

Output is the graph of the particular health type sensor provided.

get_wireless_graph

Get a particular wireless class graph for a device, if you provide a sensor_id as well then a single sensor graph will be provided. If no sensor_id value is provided then you will be sent a stacked wireless graph.

Route: /api/v0/devices/:hostname/graphs/wireless/:type(/:sensor_id)

  • hostname can be either the device hostname or id
  • type is the name of the wireless graph as returned by list_available_wireless_graphs
  • sensor_id (optional) restricts the graph to return a particular wireless sensor graph.

Input:

-

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/graphs/wireless/device_wireless_ccq

Output:

Output is a stacked graph for the wireless type provided.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/graphs/wireless/device_wireless_ccq/1

Output:

Output is the graph of the particular wireless type sensor provided.

get_graph_generic_by_hostname

Get a specific graph for a device, this does not include ports.

Route: /api/v0/devices/:hostname/:type

  • hostname can be either the device hostname or id
  • type is the type of graph you want, use [get_graphs](#function-get_graphs to see the graphs available. Defaults to device uptime.

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/device_poller_perf

Output:

Output is an image.

get_graph_by_service

Get the graph for a service

Route: /api/v0/devices/:hostname/services/:service_id/graphs/:datasource

  • hostname can be either the device hostname or id
  • service id
  • datasource is the name of the service datasource

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/services/localhost/35/graphs/loss

Output:

Output is an image.

get_port_graphs

Get a list of ports for a particular device.

Route: /api/v0/devices/:hostname/ports

  • hostname can be either the device hostname or id

Input:

  • columns: Comma separated list of columns you want returned.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/ports

Output:

{
    "status": "ok",
    "message": "",
    "count": 3,
    "ports": [
        {
            "ifName": "lo"
        },
        {
            "ifName": "eth0"
        },
        {
            "ifName": "eth1"
        }
    ]
}

get_device_fdb

Get a list of FDB entries associated with a device.

Route: /api/v0/devices/:hostname/fdb

  • hostname can be either the device hostname or id

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/fdb

Output:

{
    "status": "ok",
    "ports_fdb": {
        "ports_fdb_id": 10,
        "port_id": 10000,
        "mac_address": "1aaa2bbb3ccc",
        "vlan_id": 20000,
        "device_id": 1,
        "created_at": "2019-01-1 01:01:01",
        "updated_at": "2019-01-1 01:01:01"
    }
}

get_device_ip_addresses

Get a list of IP addresses (v4 and v6) associated with a device.

Route: /api/v0/devices/:hostname/ip

  • hostname can be either the device hostname or id

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/ip

Output:

{
    "status": "ok",
    "message": "",
    "addresses": [
        {
          "ipv4_address_id": "290",
          "ipv4_address": "192.168.99.292",
          "ipv4_prefixlen": "30",
          "ipv4_network_id": "247",
          "port_id": "323",
          "context_name": ""
        }
    ]
}

get_port_stack

Get a list of port mappings for a device. This is useful for showing physical ports that are in a virtual port-channel.

Route: /api/v0/devices/:hostname/port_stack

  • hostname can be either the device hostname or id

Input:

  • valid_mappings: Filter the result by only showing valid mappings ("0" values not shown).

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/port_stack?valid_mappings

Output:

{
  "status": "ok",
  "message": "",
  "count": 2,
  "mappings": [
    {
      "device_id": "3742",
      "port_id_high": "1001000",
      "port_id_low": "51001",
      "ifStackStatus": "active"
    },
    {
      "device_id": "3742",
      "port_id_high": "1001000",
      "port_id_low": "52001",
      "ifStackStatus": "active"
    }
  ]
}

get_device_transceivers

Get a list of FDB entries associated with a device.

Route: /api/v0/devices/:hostname/transceivers

  • hostname can be either the device hostname or id

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/transceivers

Output:

{
    "status": "ok",
    "transceivers": [
        {
            "id": 12,
            "created_at": "2024-06-26T23:46:06.000000Z",
            "updated_at": "2024-06-26T23:46:57.000000Z",
            "device_id": 3138,
            "port_id": 50735,
            "index": "50",
            "type": "10G_BASE_LR_SFP",
            "vendor": "FS",
            "oui": "00 00 00",
            "model": null,
            "revision": "",
            "serial": "G000999AA",
            "date": null,
            "ddm": true,
            "encoding": null,
            "cable": "SM",
            "distance": 20000,
            "wavelength": 1330,
            "connector": "LC",
            "channels": 1
        },
        {
            "id": 13,
            "created_at": "2024-06-26T23:46:06.000000Z",
            "updated_at": "2024-06-27T00:00:07.000000Z",
            "device_id": 3138,
            "port_id": 50736,
            "index": "51",
            "type": "10G_BASE_SR_SFP",
            "vendor": "HPE",
            "oui": "64 9D 99",
            "model": null,
            "revision": "1",
            "serial": "AAAA0000AAA",
            "date": null,
            "ddm": true,
            "encoding": null,
            "cable": "SM",
            "distance": 300,
            "wavelength": 850,
            "connector": "LC",
            "channels": 1
        }
    ]
}

get_components

Get a list of components for a particular device.

Route: /api/v0/devices/:hostname/components

  • hostname can be either the device hostname or id

Input:

  • type: Filter the result by type (Equals).
  • id: Filter the result by id (Equals).
  • label: Filter the result by label (Contains).
  • status: Filter the result by status (Equals).
  • disabled: Filter the result by disabled (Equals).
  • ignore: Filter the result by ignore (Equals).

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/components

Output:

{
    "status": "ok",
    "message": "",
    "count": 3,
    "components": {
        "2": {
            "TestAttribute-1": "Value1",
            "TestAttribute-2": "Value2",
            "TestAttribute-3": "Value3",
            "type": "TestComponent-1",
            "label": "This is a really cool blue component",
            "status": "1",
            "ignore": "0",
            "disabled": "0"
        },
        "20": {
            "TestAttribute-1": "Value4",
            "TestAttribute-2": "Value5",
            "TestAttribute-3": "Value6",
            "type": "TestComponent-1",
            "label": "This is a really cool red component",
            "status": "1",
            "ignore": "0",
            "disabled": "0"
        },
        "27": {
            "TestAttribute-1": "Value7",
            "TestAttribute-2": "Value8",
            "TestAttribute-3": "Value9",
            "type": "TestComponent-2",
            "label": "This is a really cool yellow widget",
            "status": "1",
            "ignore": "0",
            "disabled": "0"
        }
    }
}

add_components

Create a new component of a type on a particular device.

Route: /api/v0/devices/:hostname/components/:type

  • hostname can be either the device hostname or id
  • type is the type of component to add

Example:

curl -X POST -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/components/APITEST

Output:

{
    "status": "ok",
    "message": "",
    "count": 1,
    "components": {
        "4459": {
            "type": "APITEST",
            "label": "",
            "status": 1,
            "ignore": 0,
            "disabled": 0,
            "error": ""
        }
    }
}

edit_components

Edit an existing component on a particular device.

Route: /api/v0/devices/:hostname/components

  • hostname can be either the device hostname or id

In this example we set the label and add a new field: TestField:

curl -X PUT -d '{"4459": {"type": "APITEST","label": "This is a test label","status": 1,"ignore": 0,"disabled": 0,"error": "","TestField": "TestData"}}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/components

Output:

{
    "status": "ok",
    "message": "",
    "count": 1
}

Just take the JSON array from add_components or edit_components, edit as you wish and submit it back to edit components.

delete_components

Delete an existing component on a particular device.

Route: /api/v0/devices/:hostname/components/:component

  • hostname can be either the device hostname or id
  • component is the component ID to be deleted.

Example:

curl -X DELETE -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/components/4459

Output:

{
    "status": "ok",
    "message": ""
}

get_port_stats_by_port_hostname

Get information about a particular port for a device.

Route: /api/v0/devices/:hostname/ports/:ifname

  • hostname can be either the device hostname or id
  • ifname can be any of the interface names for the device which can be obtained using get_port_graphs. Please ensure that the ifname is urlencoded if it needs to be (i.e Gi0/1/0 would need to be urlencoded.

Input:

  • columns: Comma separated list of columns you want returned.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/ports/eth0

Output:

{
 "status": "ok",
 "port": {
  "port_id": "2",
  "device_id": "1",
  ...
  "poll_prev": "1418412902",
  "poll_period": "300"
 }
}

get_graph_by_port_hostname

Get a graph of a port for a particular device.

Route: /api/v0/devices/:hostname/ports/:ifname/:type

  • hostname can be either the device hostname or id
  • ifname can be any of the interface names for the device which can be obtained using get_port_graphs. Please ensure that the ifname is urlencoded if it needs to be (i.e Gi0/1/0 would need to be urlencoded.
  • type is the port type you want the graph for, you can request a list of ports for a device with get_port_graphs.

Input:

  • from: This is the date you would like the graph to start - See http://oss.oetiker.ch/rrdtool/doc/rrdgraph.en.html for more information.
  • to: This is the date you would like the graph to end - See http://oss.oetiker.ch/rrdtool/doc/rrdgraph.en.html for more information.
  • width: The graph width, defaults to 1075.
  • height: The graph height, defaults to 300.
  • ifDescr: If this is set to true then we will use ifDescr to lookup the port instead of ifName. Pass the ifDescr value you want to search as you would ifName.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/ports/eth0/port_bits

Output:

Output is an image.

list_sensors

Get a list of all Sensors.

Route: /api/v0/resources/sensors

Input:

-

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/resources/sensors

Output:

{
    "status": "ok",
    "sensors": [
        {
            "sensor_id": 218810,
            "sensor_deleted": 0,
            "sensor_class": "dbm",
            "device_id": 136,
            "poller_type": "snmp",
            "sensor_oid": ".1.3.6.1.4.1.2636.3.60.1.1.1.1.7.919",
            "sensor_index": "tx-919",
            "sensor_type": "junos",
            "sensor_descr": "xe-2/1/4 Tx Power",
            "group": null,
            "sensor_divisor": 100,
            "sensor_multiplier": 1,
            "sensor_current": -1.81,
            "sensor_limit": 2,
            "sensor_limit_warn": 0.5,
            "sensor_limit_low": -9.7,
            "sensor_limit_low_warn": -8.21,
            "sensor_alert": 1,
            "sensor_custom": "No",
            "entPhysicalIndex": "919",
            "entPhysicalIndex_measured": "ports",
            "lastupdate": "2019-02-18 02:47:09",
            "sensor_prev": -1.77,
            "user_func": null
        },
        ...
    ],
    "count": 100
}

list_devices

Return a list of devices.

Route: /api/v0/devices

Input:

  • order: How to order the output, default is by hostname. Can be prepended by DESC or ASC to change the order.
  • type: can be one of the following to filter or search by:
  • all: All devices
  • active: Only not ignored and not disabled devices
  • ignored: Only ignored devices
  • up: Only devices that are up
  • down: Only devices that are down
  • disabled: Disabled devices
  • os: search by os type
  • mac: search by mac address
  • ipv4: search by IPv4 address
  • ipv6: search by IPv6 address (compressed or uncompressed)
  • location: search by location
  • location_id: search by location_id
  • hostname: search by hostname
  • sysName: search by sysName
  • display: search by display name
  • device_id: exact match by device-id
  • type: search by device type
  • query: If searching by, then this will be used as the input.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices?order=hostname%20DESC&type=down

Output:

{
 "status": "ok",
 "count": 1,
 "devices": [
  {
   "device_id": "1",
   "hostname": "localhost",
   ...
   "serial": null,
   "icon": null
  }
 ]
}

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices?type=mac&query=00000c9ff013

Output:

{
 "status": "ok",
 "count": 1,
 "devices": [
  {
   "device_id": "1",
   "hostname": "localhost",
   ...
   "serial": null,
   "icon": null
  }
 ]
}

device_under_maintenance

Get the current maintenance status of a device.

Route: /api/v0/devices/:hostname/maintenance

Input:

-

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/maintenance

Output:

{
    "status": "ok",
    "is_under_maintenance": true
}

maintenance_device

Set a device into maintenance mode.

Route: /api/v0/devices/:hostname/maintenance

Input (JSON):

  • title: optional - Some title for the Maintenance
    Will be replaced with hostname if omitted
  • notes: optional - Some description for the Maintenance
    Will also be added to device notes if user prefs "Add schedule notes to devices notes" is set
  • start: optional - start time of Maintenance in full format Y-m-d H:i:00
    eg: 2022-08-01 22:45:00
    Current system time now() will be used if omitted
  • duration: required - Duration of Maintenance in format H:i / Hrs:Mins
    eg: 02:00

Example with start time:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
  -X POST https://librenms.org/api/v0/devices/localhost/maintenance/ \
  --data-raw '
 "title":"Device Maintenance",
  "notes":"A 2 hour Maintenance triggered via API with start time",
  "start":"2022-08-01 08:00:00",
  "duration":"2:00"
}
'

Output:

{
    "status": "ok",
    "message": "Device localhost (1) will begin maintenance mode at 2022-08-01 22:45:00 for 2:00h"
}

Example with no start time:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
  -X POST https://librenms.org/api/v0/devices/localhost/maintenance/ \
  --data-raw '
 "title":"Device Maintenance",
  "notes":"A 2 hour Maintenance triggered via API with no start time",
  "duration":"2:00"
}
'

Output:

{
    "status": "ok",
    "message": "Device localhost (1) moved into maintenance mode for 2:00h"
}

add_device

Add a new device. Most fields are optional. You may omit snmp credentials to attempt each system credential in order. See snmp.version, snmp.community, and snmp.v3

To guarantee device is added, use force_add. This will skip checks for duplicate device and snmp reachability, but not duplicate hostname.

Route: /api/v0/devices

Input (JSON):

Fields:

  • hostname (required): device hostname or IP
  • display: A string to display as the name of this device, defaults to hostname (or device_display_default setting). May be a simple template using replacements: {{ $hostname }}, {{ $sysName }}, {{ $sysName_fallback }}, {{ $ip }}
  • snmpver: SNMP version to use, v1, v2c or v3. During checks detection order is v2c,v3,v1
  • port: SNMP port (defaults to port defined in config).
  • transport: SNMP protocol (udp,tcp,udp6,tcp6) Defaults to transport defined in config.
  • port_association_mode: method to identify ports: ifIndex (default), ifName, ifDescr, ifAlias
  • poller_group: This is the poller_group id used for distributed poller setup. Defaults to 0.
  • location or location_id: set the location by text or location id

Options:

  • force_add: Skip all checks and attempts to detect credentials. Add the device as given directly to the database.
  • ping_fallback: if snmp checks fail, add the device as ping only instead of failing

SNMP v1 or v2c credentials:

  • community: Required for SNMP v1 or v2c.

SNMP v3 credentials:

  • authlevel: SNMP authlevel (noAuthNoPriv, authNoPriv, authPriv).
  • authname: SNMP Auth username
  • authpass: SNMP Auth password
  • authalgo: SNMP Auth algorithm (MD5, SHA) (SHA-224, SHA-256, SHA-384, SHA-512 if supported by your server)
  • cryptopass: SNMP Crypto Password
  • cryptoalgo: SNMP Crypto algorithm (AES, DES)

For ICMP only:

  • snmp_disable: set to true for ICMP only. Disables SNMP checks and polling.
  • os: OS short name for the device (defaults to ping).
  • sysName: sysName for the device.
  • hardware: Device hardware.

Example:

curl -X POST -d '{"hostname":"localhost.localdomain","version":"v1","community":"public"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices

Output:

{
    "status": "ok",
    "message": "Device localhost.localdomain (57) has been added successfully",
    "devices": [
        {
            "device_id": "57",
            "hostname": "localhost",
            ...
            "serial": null,
            "icon": null
        }
}

list_oxidized

List devices for use with Oxidized. If you have group support enabled then a group will also be returned based on your config.

LibreNMS will automatically map the OS to the Oxidized model name if they don't match.

Route: /api/v0/oxidized(/:hostname)

Input (JSON):

-

Examples:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/oxidized

Output:

[
    {
        "hostname": "localhost",
        "os": "linux"
    },
    {
        "hostname": "otherserver",
        "os": "linux"
    }
]

update_device_field

Update devices field in the database.

Route: /api/v0/devices/:hostname

  • hostname can be either the device hostname or id

Input (JSON):

  • field: The column name within the database (can be an array of fields)
  • data: The data to update the column with (can be an array of data))

Examples:

curl -X PATCH -d '{"field": "notes", "data": "This server should be kept online"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost

Output:

[
    {
        "status": "ok",
        "message": "Device notes has been updated"
    }
]

update_device_port_notes

Update a device port notes field in the devices_attrs database.

Route: /api/v0/devices/:hostname/port/:portid

  • hostname can be either the device hostname or id
  • portid needs to be the port unique id (int).

Input (JSON): - notes: The string data to populate on the port notes field.

Examples:

curl -X PATCH -d '{"notes": "This port is in a scheduled maintenance with the provider."}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/port/5

Output:

[
    {
        "status": "ok",
        "message": "Port notes field has been updated"
    }
]

curl -X PATCH -d '{"field": ["notes","purpose"], "data": ["This server should be kept online", "For serving web traffic"]}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost

Output:

[
    {
        "status": "ok",
        "message": "Device fields have been updated"
    }
]

rename_device

Rename device.

Route: /api/v0/devices/:hostname/rename/:new_hostname

  • hostname can be either the device hostname or id

Input:

-

Examples:

curl -X PATCH  -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/rename/localhost2

Output:

[
    {
        "status": "ok",
        "message": "Device has been renamed"
    }
]

get_device_groups

List the device groups that a device is matched on.

Route: /api/v0/devices/:hostname/groups

  • hostname can be either the device hostname or id

Input (JSON):

-

Examples:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/groups

Output:

[
    {
        "status": "ok",
        "message": "Found 1 device groups",
        "count": 1,
        "groups": [
        {
            "id": "1",
            "name": "Testing",
            "desc": "Testing",
            "pattern": "%devices.status = \"1\" &&"
        }
        ]
    }
]

search_oxidized

search all oxidized device configs for a string.

Route: api/v0/oxidized/config/search/:searchstring

  • searchstring is the specific string you would like to search for.

Input:

-

Example: 

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/oxidized/config/search/vlan10

Output: 

{
    "status": "ok",
    "nodes": [
        {
            "node": "asr9k.librenms.org",
            "full_name": "cisco\/ASR9K.Librenms.org"
        },
        {
            "node": "ios.Librenms.org",
            "full_name": "cisco\/ios.Librenms.org"
        }
    ],
    "count": 2
}

get_oxidized_config

Returns a specific device's config from oxidized.

Route: api/v0/oxidized/config/:hostname

  • hostname is the Hostname or IP of the device used when adding the device to librenms.

Input:

-

Example: 

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/oxidized/config/router.corp.com

Output: 

{
    "status": "ok",
    "config": "DEVICE CONFIG HERE"
}

add_parents_to_host

Add one or more parents to a host.

Route: /api/v0/devices/:device/parents

Input (JSON):

  • parent_ids: one or more parent ids or hostnames

Example: 

curl -X POST -d '{"parent_ids":"15,16,17"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/1/parents

Output: 

{
    "status": "ok",
    "message": "Device dependencies have been saved"
}

delete_parents_from_host

Deletes some or all the parents from a host.

Route: /api/v0/devices/:device/parents

Input (JSON):

  • parent_ids: One or more parent ids or hostnames, if not specified deletes all parents from host.

Example: 

curl -X DELETE -d '{"parent_ids":"15,16,17"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/1/parents

Output: 

{
    "status": "ok",
    "message": "All device dependencies have been removed"
}

list_parents_of_host

This is not a seperate API call. Instead, you obtain the list of parents from list_devices. See that entry point for more detailed information.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' 'http://librenms.org/api/v0/devices?type=device_id&query=34'

Output:

{
    "status": "ok",
    "devices": [
        {
            ...
            "dependency_parent_id": "98,99",
            "dependency_parent_hostname": "HOSTNAME1,HOSTNAME2",
            ...
        }
    ],
    "count": 1
}