Alerts

get_alert

Get details of an alert

Route: /api/v0/alerts/:id

● id is the alert id, you can obtain a list of alert ids from list_alerts.

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/alerts/1

Output:

{
"status": "ok",
"message": "",
"count": 7,
"alerts": [
{
"hostname": "localhost",
"id": "1",
"device_id": "1",
"rule_id": "1",
"state": "1",
"alerted": "1",
"open": "1",
"timestamp": "2014-12-11 14:40:02"
}]
}
ack_alert

Acknowledge an alert

Route: /api/v0/alerts/:id

● id is the alert id, you can obtain a list of alert ids from list_alerts.
● note is the note to add to the alert
● until_clear is a boolean and if set to false, the alert will re-alert if it
gets worse/better or changes.

Input:

Example:

curl -X PUT -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/alerts/1

Output:

{
"status": "ok",
"message": "",
"message": "Alert has been acknowledged"
}

unmute_alert

Unmute an alert

Route: /api/v0/alerts/unmute/:id

● id is the alert id, you can obtain a list of alert ids from list_alerts.

Input:

-
Example:

curl -X PUT -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/alerts/unmute/1

Output:

{
"status": "ok",
"message": "Alert has been unmuted"
}

list_alerts

List all alerts

Route: /api/v0/alerts

Input:

● state: Filter the alerts by state, 0 = ok, 1 = alert, 2 = ack

● severity: Filter the alerts by severity. Valid values are ok, warning,
critical.
● alert_rule: Filter alerts by alert rule ID.
● order: How to order the output, default is by timestamp
(descending). Can be appended by DESC or ASC to change the
order.

Examples:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/alerts?state=1

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/alerts?severity=critical
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/alerts?order=timestamp%20ASC

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/alerts?alert_rule=49

Output:

{
"status": "ok",
"message": "",
"count": 1,
"alerts": [
{
"id": "1",
"device_id": "1",
"rule_id": "1",
"state": "1",
"alerted": "1",
"open": "1",
"timestamp": "2014-12-11 14:40:02"
}]
}

Rules
get_alert_rule

Get the alert rule details.

Route: /api/v0/rules/:id

● id is the rule id.

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/rules/1

Output:

{
"status": "ok",
"message": "",
"count": 1,
"rules": [
{
"id": "1",
"device_id": "1",
"rule": "%devices.os != \"Juniper\"",
"severity": "warning",
"extra":
"{\"mute\":true,\"count\":\"15\",\"delay\":null,\"invert\":false}",
"disabled": "0",
"name": "A test rule"
}
]
}

delete_rule

Delete an alert rule by id

Route: /api/v0/rules/:id

● id is the rule id.

Input:
-

Example:

curl -X DELETE -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/rules/1

Output:

{
"status": "ok",
"message": "",
"message": "Alert rule has been removed"
}

list_alert_rules

List the alert rules.

Route: /api/v0/rules

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/rules

Output:

{
"status": "ok",
"message": "",
"count": 1,
 "rules": [
{
"id": "1",
"device_id": "-1",
"rule": "%devices.os != \"Juniper\"",
"severity": "critical",
"extra":
"{\"mute\":false,\"count\":\"15\",\"delay\":\"300\",\"invert\":false
}",
"disabled": "0",
"name": "A test rule"
}]
}

add_rule

Add a new alert rule.

Route: /api/v0/rules

Input (JSON):

● devices: This is either an array of device ids or -1 for a global rule

● builder: The rule which should be in the format entity.condition
value (i.e devices.status != 0 for devices marked as down). It must
be json encoded in the format rules are currently stored.
● severity: The severity level the alert will be raised against, Ok,
Warning, Critical.
● disabled: Whether the rule will be disabled or not, 0 = enabled, 1 =
disabled
● count: This is how many polling runs before an alert will trigger and
the frequency.
● delay: Delay is when to start alerting and how frequently. The value
is stored in seconds but you can specify minutes, hours or days by
doing 5 m, 5 h, 5 d for each one.
● interval: How often to re-issue notifications while this alert is
active,0 means notify once.The value is stored in seconds but you
can specify minutes, hours or days by doing 5 m, 5 h, 5 d for each
one.
 ● mute: If mute is enabled then an alert will never be sent but will
show up in the Web UI (true or false).
● invert: This would invert the rules check.
● name: This is the name of the rule and is mandatory.
● notes: Some informal notes for this rule

Example:

curl -X POST -d '{"devices":[1,2,3], "name": "testrule", "builder":

{"condition":"AND","rules":
[{"id":"devices.hostname","field":"devices.hostname","type":"string"
,"input":"text","operator":"equal","value":"localhost"}],"valid":tru
e},"severity": "critical","count":15,"delay":"5 m","interval":"5
m","mute":false,"notes":"This a note from the API"}' -H 'X-Auth-
Token: YOURAPITOKENHERE' https://librenms.org/api/v0/rules

Output:

{
"status": "ok"
}

edit_rule

Edit an existing alert rule

Route: /api/v0/rules

Input (JSON):

● rule_id: You must specify the rule_id to edit an existing rule, if this is
absent then a new rule will be created.
● devices: This is either an array of device ids or -1 for a global rule
● builder: The rule which should be in the format entity.condition
value (i.e devices.status != 0 for devices marked as down). It must
be json encoded in the format rules are currently stored.
● severity: The severity level the alert will be raised against, Ok,
Warning, Critical.
 ● disabled: Whether the rule will be disabled or not, 0 = enabled, 1 =
disabled
● count: This is how many polling runs before an alert will trigger and
the frequency.
● delay: Delay is when to start alerting and how frequently. The value
is stored in seconds but you can specify minutes, hours or days by
doing 5 m, 5 h, 5 d for each one.
● interval: How often to re-issue notifications while this alert is
active,0 means notify once.The value is stored in seconds but you
can specify minutes, hours or days by doing 5 m, 5 h, 5 d for each
one.
● mute: If mute is enabled then an alert will never be sent but will
show up in the Web UI (true or false).
● invert: This would invert the rules check.
● name: This is the name of the rule and is mandatory.
● notes: Some informal notes for this rule

Example:

curl -X PUT -d '{"rule_id":1,"device_id":"-1", "name": "testrule",

"builder":{"condition":"AND","rules":
[{"id":"devices.hostname","field":"devices.hostname","type":"string"
,"input":"text","operator":"equal","value":"localhost"}],"valid":tru
e},"severity": "critical","count":15,"delay":"5 m","interval":"5
m","mute":false,"notes":"This a note from the API"}' -H 'X-Auth-
Token: YOURAPITOKENHERE' https://librenms.org/api/v0/rules

Output:

{
"status": "ok"

ARP

list_arp
Retrieve a specific ARP entry or all ARP entries for a device

Route: /api/v0/resources/ip/arp/:query

Query can be: - An IP address - A MAC address - A CIDR network

(192.168.1.0/24) - all and set ?device=hostname (or device id)

Input:

● device if you specify all for the query then you need to populate this
with the hostname or id of the device.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/resources/ip/arp/1.1.1.1
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/resources/ip/arp/192.168.1.0/24
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/resources/ip/arp/all?device=localhost

Output:

{
"status": "ok",
"message": "",
"count": 1,
"arp": [
{
"port_id": "229",
"mac_address": "da160e5c2002",
"ipv4_address": "1.1.1.1",
"context_name": ""
}
]

Bills
list_bills

Retrieve the list of bills currently in the system.

Route: /api/v0/bills /api/v0/bills?period=previous

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/bills
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bills?period=previous

Output:

{
"status": "ok",
"message": "",
"count": 1,
"bills": [
{
"bill_id": "1",
"bill_name": "Router bills",
"bill_type": "cdr",
"bill_cdr": "10000000",
"bill_day": "1",
"bill_quota": "0",
"rate_95th_in": "0",
"rate_95th_out": "0",
"rate_95th": "0",
"dir_95th": "in",
"total_data": "0",
"total_data_in": "0",
"total_data_out": "0",
"rate_average_in": "0",
"rate_average_out": "0",
"rate_average": "0",
"bill_last_calc": "2015-07-02 17:01:26",
"bill_custid": "Router",
 "bill_ref": "Router",
"bill_notes": "Bill me",
"bill_autoadded": "0",
"ports_total": "0",
"allowed": "10Mbps",
"used": "0bps",
"percent": 0,
"overuse": "-",
"ports": [
{
"device_id": "168",
"port_id": "35146",
"ifName": "eth0"
}
]
}
]
}

get_bill

Retrieve a specific bill

Route: /api/v0/bills/:id /api/v0/bills/:id?period=previous

/api/v0/bills?ref=:ref /api/v0/bills?ref=:ref&period=previous
/api/v0/bills?custid=:custid /api/v0/bills?
custid=:custid&period=previous

● id is the specific bill id

● ref is the billing reference
● custid is the customer reference
● period=previous indicates you would like the data for the last
complete period rather than the current period

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/bills/1
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bills?ref=:customerref
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bills?custid=:custid

Output:

{
"status": "ok",
"message": "",
"count": 1,
"bills": [
{
"bill_id": "1",
"bill_name": "Router bills",
"bill_type": "cdr",
"bill_cdr": "10000000",
"bill_day": "1",
"bill_quota": "0",
"rate_95th_in": "0",
"rate_95th_out": "0",
"rate_95th": "0",
"dir_95th": "in",
"total_data": "0",
"total_data_in": "0",
"total_data_out": "0",
"rate_average_in": "0",
"rate_average_out": "0",
"rate_average": "0",
"bill_last_calc": "2015-07-02 17:01:26",
"bill_custid": "Router",
"bill_ref": "Router",
"bill_notes": "Bill me",
"bill_autoadded": "0",
"ports_total": "0",
"allowed": "10Mbps",
"used": "0bps",
"percent": 0,
"overuse": "-",
"ports": [
 {
"device_id": "168",
"port_id": "35146",
"ifName": "eth0"
}
]
}
]
}

get_bill_graph

Retrieve a graph image associated with a bill.

NB: The graphs returned from this will always be png as they do not come
from rrdtool, even if you have SVG set.

Route: `/api/v0/bills/:id/graphs/:graph_type

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/bills/1/graphs/bits
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bills/1/graphs/bits?from=1517443200
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bills/1/graphs/bits?
from=1517443200&to=1517788800
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bills/1/graphs/monthly

Output:

Graph Image

get_bill_graphdata
Retrieve the data used to draw a graph so it can be rendered in an external
system

Route: /api/v0/bills/:id/graphdata/:graph_type

Input:

The reducefactor parameter is used to reduce the number of data points.

Billing data has 5 minute granularity, so requesting a graph for a long time
period will result in many data points. If not supplied, it will be automatically
calculated. A reducefactor of 1 means return all items, 2 means half of the
items etc.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/bills/1/graphdata/bits
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bills/1/graphdata/bits?from=1517443200
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bills/1/graphdata/bits?
from=1517443200&to=1517788800
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bills/1/graphdata/bits?
from=1517443200&to=1517788800&reducefactor=5

Output:

{ "status": "ok", "graph_data": { "from": "1517443200", "to": 1518196161, "last":

"1518195901", "in_data": [ 103190525.20999999, 104949255.81 ], "out_data": [
1102059.1299999999, 1079216.46 ], "tot_data": [ 104292584.33999999,
106028472.27 ], "ticks": [ "1517750401", "1517756101" ], "rate_95th":
"251880417", "rate_average": "146575554", "bill_type": "cdr", "max_in":
9888289942, "max_out": 75848756, "ave_in": 18029660.242105871, "ave_out":
196447.38060137472, "last_in": 3790227.9500000002, "last_out":
122731.63333333333 } }

get_bill_history

Retrieve the history of specific bill

Route: /api/v0/bills/:id/history
Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/bills/1/history

Output:

{
"status": "ok",
"bill_history": [
{
"bill_hist_id": "1",
"bill_id": "1",
"updated": "2018-02-06 17:01:01",
"bill_datefrom": "2018-02-01 00:00:00",
"bill_dateto": "2018-02-28 23:59:59",
"bill_type": "CDR",
"bill_allowed": "100000000",
"bill_used": "229963765",
"bill_overuse": "129963765",
"bill_percent": "229.96",
"rate_95th_in": "229963765",
"rate_95th_out": "1891344",
"rate_95th": "229963765",
"dir_95th": "in",
"rate_average": "136527101",
"rate_average_in": "135123359",
"rate_average_out": "1403743",
"traf_in": "3235123452544",
"traf_out": "33608406566",
"traf_total": "3268731859110",
"bill_peak_out": "2782349290",
"bill_peak_in": "10161119",
"pdf": null
}
],
"count": 1,
}
get_bill_history_graph

Retrieve a graph of a previous period of a bill

NB: The graphs returned from this will always be png as they do not come
from rrdtool, even if you have SVG set.

Route: /api/v0/bills/:id/history/:bill_hist_id/graphs/:graph_type

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/bills/1/history/1/graphs/bits
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bills/1/history/1/graphs/hour
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bills/1/history/1/graphs/day

Output:

(image)

get_bill_history_graphdata

Retrieve the data for a graph of a previous period of a bill, to be rendered in an

external system

Route: /api/v0/bills/:id/history/:bill_hist_id/graphdata/:graph_type

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/bills/1/history/1/graphdata/bits
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bills/1/history/1/graphdata/hour
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bills/1/history/1/graphdata/day

Output:

delete_bill

Delete a specific bill and all dependent data

Route: /api/v0/bills/:id

● id is the specific bill id

Input:

Example:

curl -X DELETE -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/bills/1

Output:

{
"status": "ok",
"message": "Bill has been removed"
}

create_edit_bill

Creates a new bill or updates an existing one

Route: /api/v0/bills

Method: POST

● If you send an existing bill_id the call replaces all values it receives.
For example if you send 2 ports it will delete the existing ports and
 add the the 2 new ports. So to add ports you have to get the current
ports first and add them to your update call.

Input:

Example (create):

curl -X POST -d '{"ports":

[ 1021 ],"bill_name":"NEWBILL","bill_day":"1","bill_type":"quota","b
ill_quota":"2000000000000","bill_custid":"1337","bill_ref":"referenc
e1","bill_notes":"mynote"}' -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bills

Example (set):

curl -X POST -d '{"bill_id":"32","ports":

[ 1021 ],"bill_name":"NEWNAME","bill_quota":"1000000000000"}' -H 'X-
Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills

Output:

{
"status": "ok",
"bill_id": 32

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\",\"t
ype\":\"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"
}

update_devicegroup

Updates a device group.

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):

● name: optional - The name of the device group

● type: optional - 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:

curl -X PATCH -d '{"name": "NewLinuxServers"}' -H 'X-Auth-Token:

YOURAPITOKENHERE' https://librenms.org/api/v0/devices/LinuxServers

Output:

{
"status": "ok",
"message": "Device group LinuxServers updated"
}
delete_devicegroup

Deletes a device group.

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:

Examples:

curl -X DELETE -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/devices/LinuxServers

Output:

{
"status": "ok",
"message": "Device group LinuxServers deleted"
}

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/devicegroups/:name/maintenance

Input (JSON):

● title: optional - Some title for the Maintenance

Will be replaced with device group name if omitted
 ● notes: optional - Some description for the Maintenance
● 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/devicegroups/Cisco
%20switches/maintenance/ \
--data-raw '
{
"title":"Device group 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 group Cisco switches (2) 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/devicegroups/Cisco
%20switches/maintenance/ \
--data-raw '
{
"title":"Device group Maintenance",
 "notes":"A 2 hour Maintenance triggered via API with no start
time",
"duration":"2:00"
}
'

Output:

{
"status": "ok",
"message": "Device group Cisco switches (2) moved into
maintenance mode for 2:00h"
}

Add devices to group

Add devices to a device group.

Route: /api/v0/devicegroups/:name/devices

● 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):

● devices: required - A list of devices to be added to the group.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' \

-X POST https://librenms.org/api/v0/devicegroups/devices \
--data-raw '{"devices":[261,271]}'

Output:

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

Remove devices from group

Removes devices from a device group.

Route: /api/v0/devicegroups/:name/devices

● 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):

● devices: required - A list of devices to be removed from the group.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' \

-X DELETE https://librenms.org/api/v0/devicegroups/devices \
--data-raw '{"devices":[261,271]}'

Output:

{
"status": "ok",
"message": "Devices removed"

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_wirele
ss_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_v
oltage

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_v
oltage/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](#get_graphs to
see the graphs available. Defaults to device uptime.

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.
● output: Set how the graph should be outputted (base64, display),
defaults to display.

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:

● 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.

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_nac

Get a list of NAC entries associated with a device.

Route: /api/v0/devices/:hostname/nac

● hostname can be either the device hostname or id

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/devices/localhost/nac

Output:

{
"status": "ok",
"ports_nac": [
{
"ports_nac_id": 1,
"auth_id": "0000000000000AAAABBBB8CC",
"device_id": 3,
"port_id": 6,
"domain": "data",
"username": "hostname.librenms.org",
"mac_address": "1aaa2bbb3ccc",
"ip_address": "192.0.2.2",
"host_mode": "singleHost",
"authz_status": "authorizationSuccess",
"authz_by": "Authentication Server",
"authc_status": "authcSuccess",
"method": "dot1x",
"timeout": "0",
"time_left": "0",
"vlan": 0,
"time_elapsed": null,
"created_at": "2025-05-08T08:55:06.000000Z",
"updated_at": "2025-05-08T08:55:06.000000Z",
 "historical": 0
}
]
}

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
● serial: Serial number of the device (wildcard)
● version: Software version of the device (wildcard)
 ● hardware: The model of the device (wildcard)
● features: Software license features (wildcard)
● 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
● override_sysLocation: force use of the location/location_id: and not
the value returned by sysLocation

Options:

● force_add: Skip all checks, credentials are required. 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":"pub
lic"}' -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 separate 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

Inventory

get_inventory

Retrieve the inventory for a device. If you call this without any parameters then
you will only get part of the inventory. This is because a lot of devices nest
each component, for instance you may initially have the chassis, within this
the ports - 1 being an sfp cage, then the sfp itself. The way this API call is
designed is to enable a recursive lookup. The first call will retrieve the root
entry, included within this response will be entPhysicalIndex, you can then call
for entPhysicalContainedIn which will then return the next layer of results. To
retrieve all items together, see get_inventory_for_device.

Route: /api/v0/inventory/:hostname

● hostname can be either the device hostname or the device id

Input:

● entPhysicalClass: This is used to restrict the class of the inventory,

for example you can specify chassis to only return items in the
inventory that are labelled as chassis.
● entPhysicalContainedIn: This is used to retrieve items within the
inventory assigned to a previous component, for example specifying
the chassis (entPhysicalIndex) will retrieve all items where the
chassis is the parent.

Example:
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/inventory/localhost?
entPhysicalContainedIn=65536

Output:

{
"status": "ok",
"message": "",
"count": 1,
"inventory": [
{
"entPhysical_id": "2",
"device_id": "32",
"entPhysicalIndex": "262145",
"entPhysicalDescr": "Linux 3.3.5 ehci_hcd RB400 EHCI",
"entPhysicalClass": "unknown",
"entPhysicalName": "1:1",
"entPhysicalHardwareRev": "",
"entPhysicalFirmwareRev": "",
"entPhysicalSoftwareRev": "",
"entPhysicalAlias": "",
"entPhysicalAssetID": "",
"entPhysicalIsFRU": "false",
"entPhysicalModelName": "0x0002",
"entPhysicalVendorType": "zeroDotZero",
"entPhysicalSerialNum": "rb400_usb",
"entPhysicalContainedIn": "65536",
"entPhysicalParentRelPos": "-1",
"entPhysicalMfgName": "0x1d6b",
"ifIndex": "0"
}
]
}

get_inventory_for_device
Retrieve the flattened inventory for a device. This retrieves all inventory items
for a device regardless of their structure, and may be more useful for devices
with with nested components.

Route: /api/v0/inventory/:hostname/all

● hostname can be either the device hostname or the device id

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/inventory/localhost?
entPhysicalContainedIn=65536

Output:

{
"status": "ok",
"message": "",
"count": 1,
"inventory": [
{
"entPhysical_id": "2",
"device_id": "32",
"entPhysicalIndex": "262145",
"entPhysicalDescr": "Linux 3.3.5 ehci_hcd RB400 EHCI",
"entPhysicalClass": "unknown",
"entPhysicalName": "1:1",
"entPhysicalHardwareRev": "",
"entPhysicalFirmwareRev": "",
"entPhysicalSoftwareRev": "",
"entPhysicalAlias": "",
"entPhysicalAssetID": "",
"entPhysicalIsFRU": "false",
"entPhysicalModelName": "0x0002",
"entPhysicalVendorType": "zeroDotZero",
"entPhysicalSerialNum": "rb400_usb",
"entPhysicalContainedIn": "65536",
"entPhysicalParentRelPos": "-1",
"entPhysicalMfgName": "0x1d6b",
"ifIndex": "0"
 }
]

Locations

list_locations

Return a list of locations.

Route: /api/v0/resources/locations

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/resources/locations

Output:

{
"status": "ok",
"locations": [
{
"id": "1",
"location": "Example location, Example city, Example
Country",
"lat": "-18.911436",
"lng": "47.517446",
"timestamp": "2017-04-01 02:40:05"
},
...
],
 "count": 100
}

add_location

Add a new location

Route: /api/v0/locations/

Input:

● location: name of the new location

● lat: latitude
● lng: longitude
● fixed_coordinates: 0 if updated from the device or 1 if the
coordinate is fixed (default is fixed if lat and lng are valid)

Example:

curl -X POST -d '{"location":"Google", "lat":"37.4220041","lng":"-

122.0862462"}' -H 'X-Auth-Token:YOUR-API-TOKEN'
https://librenms.org/api/v0/locations

Output:

{
"status": "ok",
"message": "Location added with id #45"
}

delete_location

Deletes an existing location

Route: /api/v0/locations/:location

● location: name or id of the location to delete

Example:

curl -X DELETE -H 'X-Auth-Token:YOUR-API-TOKEN'

https://librenms.org/api/v0/locations/Google

Output:

{
"status": "ok",
"message": "Location Google has been deleted successfully"

edit_location

Edits a location

Route: /api/v0/locations/:location

● location: name or id of the location to edit

Input:

● lat: latitude
● lng: longitude

Example:

curl -X PATCH -d '{"lng":"100.0862462"}' -H 'X-Auth-Token:YOUR-API-

TOKEN' https://librenms.org/api/v0/locations/Google

Output:

{
"status": "ok",
"message": "Location updated successfully"
}
get_location

Gets a specific location

Route: /api/v0/location/:location

● location: name or id of the location to get

Output:

{
"status": "ok",
"get_location": [
{
"id": 1,
"location": "TEST",
"lat": 00.000000,
"lng": 00.000000,
"timestamp": "2023-01-01 00:00:00",
"fixed_coordinates": 1
}
],
"count": 1

Logs
All the list_*logs calls are aliased to list_logs.

Retrieve all logs or logs for a specific device.

● id or hostname is the specific device

Input:
 ● start: The page number to request.
● limit: The limit of results to be returned.
● from: The date and time or the event id to search from.
● to: The data and time or the event id to search to.

list_eventlog

Route: /api/v0/logs/eventlog/:hostname

list_syslog

Route: /api/v0/logs/syslog/:hostname

list_alertlog

Route: /api/v0/logs/alertlog/:hostname

list_authlog

Route: /api/v0/logs/authlog/:hostname

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/logs/eventlog/:hostname
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/logs/syslog/:hostname?limit=20
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/logs/eventlog/:hostname?limit=20&start=5&from=2017-
07-22%2023:00:00
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/logs/eventlog/:hostname?sortorder=DESC

Output:

{
"status": "ok",
"message": "",
"count": 5,
 "total": "15",
"logs": [
{
"hostname": "localhost",
"sysName": "web01.1.novalocal",
"event_id": "10050349",
"host": "279",
"device_id": "279",
"datetime": "2017-07-22 19:57:47",
"message": "ifAlias: -> <pptp-something-something-tunnel-
something>",
"type": "interface",
"reference": "NULL",
"username": "",
"severity": "3"
},
....
{
"hostname": "localhost",
"sysName": "web01.1.novalocal",
"event_id": "10050353",
"host": "279",
"device_id": "279",
"datetime": "2017-07-22 19:57:47",
"message": "ifHighSpeed: -> 0",
"type": "interface",
"reference": "NULL",
"username": "",
"severity": "3"
}
]
}

syslogsink

Route: /api/v0/logs/syslogsink

Accept any json messages and passes to further syslog processing. single messages or an
array of multiple messages is accepted. see Syslog for more details and logstash integration

Example

curl -L -X POST 'https://sink.librenms.org/api/v0/syslogsink/' -H 'X-Auth-

Token: xxxxxxxLibreNMSApiToken' --data-raw '[
 {
"msg": "kernel: minimum Message",
"host": "mydevice.fqdn.com"
},
{
"msg": "Line protocol on Interface GigabitEthernet1/0/41, changed state
to up",
"facility": 23,
"priority": "189",
"program": "LINEPROTO-5-UPDOWN",
"host": "172.29.10.24",
"@timestamp": "2022-12-01T20:14:28.257Z",
"severity": 5,
"level": "ERROR"
},
{
"msg": "kernel: a unknown host",
"host": "unknown.fqdn.com"
}
]'

Back to top

PollerGroups

get_poller_group

Gets a specific poller group or all if none is specified

Route: /api/v0/poller_group/:poller_group

● poller_group: optional name or id of the poller group to get

Output:

{
"status": "ok",
"get_poller_group": [
{
"id": 1,
"group_name": "test",
"descr": "test group"
}
 ],
"count": 1

Port_Groups

get_port_groups

List all port groups.

Route: /api/v0/port_groups

Examples:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/port_groups

Output:

[
{
"status": "ok",
"message": "Found 1 port groups",
"count": 1,
"groups": [
{
"id": "1",
"name": "Testing",
"desc": "Testing"
}
]
}
]
get_ports_by_group

List all ports matching the group provided.

Route: /api/v0/port_groups/:name

● name Is the name of the port group which can be obtained using
get_port_groups. Please ensure that the name is urlencoded if it
needs to be (i.e Linux Servers would need to be urlencoded.

Params:

● 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/port_groups/Billable

Output:

{
"status": "ok",
"ports": [
{
"port_id": 1376
},
{
"port_id": 2376
}
],
"count": 2
}

add_port_group

Add a new port group. Upon success, the ID of the new port group is returned
and the HTTP response code is 201.
Route: /api/v0/port_groups

Input (JSON):

● name: required - The name of the port group

● desc: optional - Description of the port group

Examples:

Dynamic Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' \

-X POST \
-d '{"name": "New Port Group", \
"desc": "A very fancy port group"}' \
https://librenms.org/api/v0/port_groups

Output:

{
"status": "ok",
"id": 86,
"message": "Port group New Port Group created"
}

assign_port_group

Assign a Port Group to a list of Ports

Route: /api/v0/port_groups/:port_group_id/assign

Input (JSON):

● port_ids: required - List of Port Ids

Examples:

Dynamic Example:
curl -H 'X-Auth-Token: YOURAPITOKENHERE' -X POST -d '{"port_ids":
["4","34","25,"983"]}'
https://librenms.org/api/v0/port_groups/3/assign

Output:

{
"status": "ok",
"Port Ids 4, 34, 25, 983 have been added to Port Group Id 3":
200
}

remove_port_group

Remove a Port Group from a list of Ports

Route: /api/v0/port_groups/:port_group_id/remove

Input (JSON):

● port_ids: required - List of Port Ids

Examples:

Dynamic Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' -X POST -d '{"port_ids":

["4","34","25,"983"]}'
https://librenms.org/api/v0/port_groups/3/remove

Output:

{
"status": "ok",
"Port Ids 4, 34, 25, 983 have been removed from Port Group Id
3": 200

}
PortGroups

get_graph_by_portgroup

Get the graph based on the group type.

Route: /api/v0/portgroups/:group

● group is the type of port group graph you want, I.e Transit, Peering,
etc. You can specify multiple types comma separated.

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.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/portgroups/transit,peering

Output:

Output is an image.

get_graph_by_portgroup_multiport_bits

Get the graph based on the multiple port id separated by commas ,.

Route: /api/v0/portgroups/multiport/bits/:id

● id is a comma separated list of port ids you want, I.e 1,2,3,4, etc.
You can specify multiple IDs comma separated.
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.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/portgroups/multiport/bits/1,2,3

Output:

Output is an image.

Ports

get_all_ports

Get info for all ports on all devices. Strongly recommend that you use the
columns parameter to avoid pulling too much data.

Route: /api/v0/ports

Input:

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

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/ports?columns=ifName%2Cport_id
Output:

{
"status": "ok",
"message": "",
"ports": [
{
"ifName": "Gi0/0/0",
"port_id": "1"
},
{
"ifName": "Gi0/0/1",
"port_id": "2"
},
...
{
"ifName": "Vlan 3615",
"port_id": "5488"
}
]
}

search_ports

Search for ports matching the query.

Route: /api/v0/ports/search/:search

● search string to search in fields: ifAlias, ifDescr, and ifName

Input:

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

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/ports/search/lo
Output:

{
"status": "ok",
"ports": [
{
"device_id": 1,
"port_id": 1,
"ifIndex": 1,
"ifName": "lo"
},
{
"device_id": 2,
"port_id": 3,
"ifIndex": 1,
"ifName": "lo"
},
{
"device_id": 3,
"port_id": 5,
"ifIndex": 1,
"ifName": "lo"
}
]
}

search_ports in specific field(s)

Specific search for ports matching the query.

Route: /api/v0/ports/search/:field/:search

● field: comma separated list of field(s) to search

● search: string to search in fields

Input:

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

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/ports/search/ifName/lo

Output:

{
"status": "ok",
"ports": [
{
"device_id": 1,
"port_id": 1,
"ifIndex": 1,
"ifName": "lo"
},
{
"device_id": 2,
"port_id": 3,
"ifIndex": 1,
"ifName": "lo"
},
{
"device_id": 3,
"port_id": 5,
"ifIndex": 1,
"ifName": "lo"
}
]
}

ports_with_associated_mac

Search for ports matching the search mac.

Route: /api/v0/ports/mac/:search?filter=first
 ● search a mac address in fdb and print the ports ordered by the mac
count of the associated port.

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/ports/mac/00:11:22:33:44:55
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/ports/mac/001122.334455?filter=first
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/ports/mac/001122334455?filter=first

Output:

{
"status": "ok",
"message": "",
"port": [
{
"port_id": "323",
"device_id": "55",
"port_descr_type": null,
"port_descr_descr": null,
"port_descr_circuit": null,
"port_descr_speed": null,
"port_descr_notes": null,
"ifDescr": "GigabitEthernet0/0/0",
"ifName": "Gi0/0/0",
"portName": null,
"ifIndex": "1",
"ifSpeed": "1000000000",
"ifConnectorPresent": "true",
"ifPromiscuousMode": "false",
"ifHighSpeed": "1000",
"ifOperStatus": "up",
"ifOperStatus_prev": null,
"ifAdminStatus": "up",
"ifAdminStatus_prev": null,
"ifDuplex": "fullDuplex",
"ifMtu": "1560",
"ifType": "ethernetCsmacd",
"ifAlias": "ASR Interconnect Trunk",
"ifPhysAddress": "84bf20853e00",
"ifHardType": null,
"ifLastChange": "42407358",
"ifVlan": "",
"ifTrunk": "",
"ifVrf": "0",
"counter_in": null,
"counter_out": null,
"ignore": "0",
"disabled": "0",
"detailed": "0",
"deleted": "0",
"pagpOperationMode": null,
"pagpPortState": null,
"pagpPartnerDeviceId": null,
"pagpPartnerLearnMethod": null,
"pagpPartnerIfIndex": null,
"pagpPartnerGroupIfIndex": null,
"pagpPartnerDeviceName": null,
"pagpEthcOperationMode": null,
"pagpDeviceId": null,
"pagpGroupIfIndex": null,
"ifInUcastPkts": "128518576",
"ifInUcastPkts_prev": "128517284",
"ifInUcastPkts_delta": "1292",
"ifInUcastPkts_rate": "4",
"ifOutUcastPkts": "128510560",
"ifOutUcastPkts_prev": "128509268",
"ifOutUcastPkts_delta": "1292",
"ifOutUcastPkts_rate": "4",
"ifInErrors": "0",
"ifInErrors_prev": "0",
"ifInErrors_delta": "0",
"ifInErrors_rate": "0",
"ifOutErrors": "0",
"ifOutErrors_prev": "0",
"ifOutErrors_delta": "0",
 "ifOutErrors_rate": "0",
"ifInOctets": "12827393730",
"ifInOctets_prev": "12827276736",
"ifInOctets_delta": "116994",
"ifInOctets_rate": "387",
"ifOutOctets": "14957481766",
"ifOutOctets_prev": "14957301765",
"ifOutOctets_delta": "180001",
"ifOutOctets_rate": "596",
"poll_time": "1483779150",
"poll_prev": "1483778848",
"poll_period": "302"
}
]
}

get_port_info

Get all info for a particular port.

Route: /api/v0/ports/:portid?with=vlans

● portid must be an integer

● it's possible to add allowed associated relations to the port using
the with option. Allowed: vlans,device

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/ports/323

Output:

{
"status": "ok",
"message": "",
"port": [
{
"port_id": "323",
"device_id": "55",
"port_descr_type": null,
"port_descr_descr": null,
"port_descr_circuit": null,
"port_descr_speed": null,
"port_descr_notes": null,
"ifDescr": "GigabitEthernet0/0/0",
"ifName": "Gi0/0/0",
"portName": null,
"ifIndex": "1",
"ifSpeed": "1000000000",
"ifConnectorPresent": "true",
"ifPromiscuousMode": "false",
"ifHighSpeed": "1000",
"ifOperStatus": "up",
"ifOperStatus_prev": null,
"ifAdminStatus": "up",
"ifAdminStatus_prev": null,
"ifDuplex": "fullDuplex",
"ifMtu": "1560",
"ifType": "ethernetCsmacd",
"ifAlias": "ASR Interconnect Trunk",
"ifPhysAddress": "84bf20853e00",
"ifHardType": null,
"ifLastChange": "42407358",
"ifVlan": "",
"ifTrunk": "",
"ifVrf": "0",
"counter_in": null,
"counter_out": null,
"ignore": "0",
"disabled": "0",
"detailed": "0",
"deleted": "0",
"pagpOperationMode": null,
"pagpPortState": null,
"pagpPartnerDeviceId": null,
"pagpPartnerLearnMethod": null,
 "pagpPartnerIfIndex": null,
"pagpPartnerGroupIfIndex": null,
"pagpPartnerDeviceName": null,
"pagpEthcOperationMode": null,
"pagpDeviceId": null,
"pagpGroupIfIndex": null,
"ifInUcastPkts": "128518576",
"ifInUcastPkts_prev": "128517284",
"ifInUcastPkts_delta": "1292",
"ifInUcastPkts_rate": "4",
"ifOutUcastPkts": "128510560",
"ifOutUcastPkts_prev": "128509268",
"ifOutUcastPkts_delta": "1292",
"ifOutUcastPkts_rate": "4",
"ifInErrors": "0",
"ifInErrors_prev": "0",
"ifInErrors_delta": "0",
"ifInErrors_rate": "0",
"ifOutErrors": "0",
"ifOutErrors_prev": "0",
"ifOutErrors_delta": "0",
"ifOutErrors_rate": "0",
"ifInOctets": "12827393730",
"ifInOctets_prev": "12827276736",
"ifInOctets_delta": "116994",
"ifInOctets_rate": "387",
"ifOutOctets": "14957481766",
"ifOutOctets_prev": "14957301765",
"ifOutOctets_delta": "180001",
"ifOutOctets_rate": "596",
"poll_time": "1483779150",
"poll_prev": "1483778848",
"poll_period": "302"
}
]
}

get_port_ip_info
Get all IP info (v4 and v6) for a given port id.

Route: /api/v0/ports/:portid/ip

● portid must be an integer

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/ports/323/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_transceiver

Get transceiver info with metrics

Route: /api/v0/ports/:portid/transceiver

● portid must be an integer

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/ports/50736/transceiver

Output:

{
"status": "ok",
"transceivers": [
{
"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": "AAA0000AAA00",
"date": null,
"ddm": true,
"encoding": null,
"cable": "MM",
"distance": 300,
"wavelength": 850,
"connector": "LC",
"channels": 1
}
]
}

get_port_description
Get the description (ifAlias) for a given port id.

Route: /api/v0/ports/:portid/description

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/ports/323/description

Output:

{
"status": "ok",
"port_description": "GigabitEthernet14"
}

update_port_description

Change the description (ifAlias) for a given port id.

Route: /api/v0/ports/:portid/description

Input (JSON):

● description: The string data to use as the new port description.

Sending an empty string will reset the description to default.

Example:

curl -X PATCH -d '{"description": "Out-of-Band Management Link"}' -H

'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/ports/323/description

Output:

{
"status": "ok",
"message": "Port description updated."
}

Routing

list_bgp

List the current BGP sessions.

Route: /api/v0/bgp

Input:

● hostname = Either the devices hostname or id.

● asn = The local ASN you would like to filter by
● remote_asn = Filter by remote peer ASN
● remote_address = Filter by remote peer address
● local_address = Filter by local address
● bgp_descr = Filter by BGP neighbor description
● bgp_state = Filter by BGP session state (like established,idle...)
● bgp_state = Filter by BGP admin state (start,stop,running...)
● bgp_family = Filter by BGP address Family (4,6)

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/bgp
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bgp?hostname=host.example.com
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bgp?asn=1234
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bgp?remote_asn=1234
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bgp?
local_address=1.1.1.1&remote_address=2.2.2.2
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bgp?bgp_descr=UPSTREAM
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bgp?bgp_state=established
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bgp?bgp_adminstate=start
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bgp?bgp_family=6
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/bgp?
bgp_state=idle&bgp_descr=CORE&bgp_family=4

Output:

{
"status": "ok",
"message": "",
"bgp_sessions": [
{
"bgpPeer_id": 1260,
"device_id": 7,
"vrf_id": null,
"astext": "Acme Ltd",
"bgpPeerIdentifier":
"2001:0DB8:0000:24cb:0000:0000:0000:0001",
"bgpPeerRemoteAs": 65432,
"bgpPeerState": "established",
"bgpPeerAdminStatus": "start",
"bgpPeerLastErrorCode": 6,
"bgpPeerLastErrorSubCode": 2,
"bgpPeerLastErrorText": "administrative shutdown",
"bgpPeerIface": 268,
"bgpLocalAddr":
"2001:0DB8:0000:24cb:0000:0000:0000:0002",
"bgpPeerRemoteAddr": "0.0.0.0",
"bgpPeerDescr": "Another one #CORE",
"bgpPeerInUpdates": 283882969,
"bgpPeerOutUpdates": 7008,
"bgpPeerInTotalMessages": 283883031,
"bgpPeerOutTotalMessages": 1386692,
"bgpPeerFsmEstablishedTime": 1628487,
"bgpPeerInUpdateElapsedTime": 0,
"context_name": ""
},
 ...
],
"count": 100
}

get_bgp

Retrieves a BGP session by ID

Route: /api/v0/bgp/:id

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/bgp/4

Output:

{
"status": "ok",
"bgp_session": [
{
"bgpPeer_id": "4",
"device_id": "2",
"astext": "",
"bgpPeerIdentifier": "1234:1b80:1:12::2",
"bgpPeerRemoteAs": "54321",
"bgpPeerState": "established",
"bgpPeerAdminStatus": "running",
"bgpLocalAddr": "1234:1b80:1:12::1",
"bgpPeerRemoteAddr": "0.0.0.0",
"bgpPeerInUpdates": "3",
"bgpPeerOutUpdates": "1",
"bgpPeerInTotalMessages": "0",
"bgpPeerOutTotalMessages": "0",
 "bgpPeerFsmEstablishedTime": "0",
"bgpPeerInUpdateElapsedTime": "0",
"context_name": ""
}
],
"count": 1
}

edit_bgp_descr

This is a POST type request Set the BGP session description by ID

Route: /api/v0/bgp/:id

Input:

● id = The id of the BGP Peer Session.

● bgp_descr = The description for the bgpPeerDescr field on the BGP
Session.

Example:

curl -v -H 'X-Auth-Token: YOURAPITOKENHERE' --data '{"bgp_descr":

"Your description here"}' https://librenms.org/api/v0/bgp/4

Output:

{
"status": "ok",
"message": "BGP description for peer X.X.X.X on device 1 updated
to Your description here"
}

list_cbgp

List the current BGP sessions counters.

Route: /api/v0/routing/bgp/cbgp

Input:

● hostname = Either the devices hostname or id

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/routing/bgp/cbgp
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/routing/bgp/cbgp?
hostname=host.example.com

Output:

{
"status": "ok",
"bgp_counters": [
{
"device_id": "9",
"bgpPeerIdentifier": "192.168.99.31",
"afi": "ipv4",
"safi": "multicast",
"AcceptedPrefixes": "2",
"DeniedPrefixes": "0",
"PrefixAdminLimit": "0",
"PrefixThreshold": "0",
"PrefixClearThreshold": "0",
"AdvertisedPrefixes": "11487",
"SuppressedPrefixes": "0",
"WithdrawnPrefixes": "10918",
"AcceptedPrefixes_delta": "-2",
"AcceptedPrefixes_prev": "2",
"DeniedPrefixes_delta": "0",
"DeniedPrefixes_prev": "0",
"AdvertisedPrefixes_delta": "-11487",
"AdvertisedPrefixes_prev": "11487",
"SuppressedPrefixes_delta": "0",
"SuppressedPrefixes_prev": "0",
"WithdrawnPrefixes_delta": "-10918",
 "WithdrawnPrefixes_prev": "10918",
"context_name": ""
},
...
],
"count": 100
}

list_ip_addresses

List all IPv4 and IPv6 or only version specific addresses.

Route: /api/v0/resources/ip/addresses/:address_family

Input:

● address_family: optional ipv4 or ipv6 for ip version specific list.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/resources/ip/addresses
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/resources/ip/addresses/ipv4
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/resources/ip/addresses/ipv6

Output:

{
"status": "ok",
"ip_addresses": [
{
"ipv4_address_id": "69",
"ipv4_address": "127.0.0.1",
"ipv4_prefixlen": "8",
"ipv4_network_id": "55",
"port_id": "135",
"context_name": ""
 },
...
],
"count": 55
}

get_network_ip_addresses

Get all IPv4 and IPv6 addresses for particular network.

Route: /api/v0/resources/ip/networks/:id/ip

● id must be integer

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/resources/ip/networks/55/ip

Output:

{
"status": "ok",
"addresses": [
{
"ipv4_address_id": "69",
"ipv4_address": "127.0.0.1",
"ipv4_prefixlen": "8",
"ipv4_network_id": "55",
"port_id": "135",
"context_name": ""
}
],
"count": 1
}
list_ip_networks

List all IPv4 and IPv6 or only version specific networks.

Route: /api/v0/resources/ip/networks/:address_family

Input:

● address_family: optional ipv4 or ipv6 for ip version specific list.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/resources/ip/networks
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/resources/ip/networks/ipv4
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/resources/ip/networks/ipv6

Output:

{
"status": "ok",
"ip_networks": [
{
"ipv4_network_id": "1",
"ipv4_network": "127.0.0.0/8",
"context_name": ""
},
...
],
"count": 100
}

list_ipsec
List the current IPSec tunnels which are active.

Route: /api/v0/routing/ipsec/data/:hostname

● hostname can be either the device hostname or id

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/routing/ipsec/data/localhost

Output:

{
"status": "ok",
"message": "",
"count": 0,
"ipsec": [
"tunnel_id": "1",
"device_id": "1",
"peer_port": "0",
"peer_addr": "127.0.0.1",
"local_addr": "127.0.0.2",
"local_port": "0",
"tunnel_name": "",
"tunnel_status": "active"
]
}

Please note, this will only show active VPN sessions not all configured.

list_ospf

List the current OSPF neighbours.

Route: /api/v0/ospf

Input:

● hostname = Either the devices hostname or id.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/ospf
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/ospf?hostname=host.example.com

Output:

{
"status": "ok",
"ospf_neighbours": [
{
"device_id": "1",
"port_id": "0",
"ospf_nbr_id": "172.16.1.145.0",
"ospfNbrIpAddr": "172.16.1.145",
"ospfNbrAddressLessIndex": "0",
"ospfNbrRtrId": "172.16.0.140",
"ospfNbrOptions": "82",
"ospfNbrPriority": "1",
"ospfNbrState": "full",
"ospfNbrEvents": "5",
"ospfNbrLsRetransQLen": "0",
"ospfNbmaNbrStatus": "active",
"ospfNbmaNbrPermanence": "dynamic",
"ospfNbrHelloSuppressed": "false",
"context_name": ""
}
],
"count": 1
}
list_ospf_ports

List the current OSPF ports.

Route: /api/v0/ospf_ports

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/ospf_ports

Output:

{
"status": "ok",
"ospf_ports": [
{
"id": 189086,
"device_id": 43,
"port_id": 2838,
"ospf_port_id": "10.10.2.86.0",
"ospfIfIpAddress": "10.10.2.86",
"ospfAddressLessIf": 0,
"ospfIfAreaId": "0.0.0.0",
"ospfIfType": "pointToPoint",
"ospfIfAdminStat": "enabled",
"ospfIfRtrPriority": 128,
"ospfIfTransitDelay": 1,
"ospfIfRetransInterval": 5,
"ospfIfHelloInterval": 10,
"ospfIfRtrDeadInterval": 40,
"ospfIfPollInterval": 90,
"ospfIfState": "pointToPoint",
"ospfIfDesignatedRouter": "0.0.0.0",
"ospfIfBackupDesignatedRouter": "0.0.0.0",
"ospfIfEvents": 33,
"ospfIfAuthKey": "",
"ospfIfStatus": "active",
"ospfIfMulticastForwarding": "unicast",
"ospfIfDemand": "false",
"ospfIfAuthType": "0",
 "ospfIfMetricIpAddress": "10.10.2.86",
"ospfIfMetricAddressLessIf": 0,
"ospfIfMetricTOS": 0,
"ospfIfMetricValue": 10,
"ospfIfMetricStatus": "active",
"context_name": null
}
],
"count": 1
}

list_ospfv3

List the current OSPFv3 neighbours.

Route: /api/v0/ospfv3

Input:

● hostname = Either the devices hostname or id.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/ospfv3
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/ospfv3?hostname=host.example.com

Output:

{
"status": "ok",
"ospfv3_neighbours": [
{
"id": 7,
"device_id": 14,
"ospfv3_instance_id": 7,
"port_id": 2345,
"router_id": "10.0.43.11",
 "ospfv3NbrIfIndex": 2,
"ospfv3NbrIfInstId": 0,
"ospfv3NbrRtrId": 167797515,
"ospfv3NbrAddressType": "ipv6",
"ospfv3NbrAddress": "fe80::1d7:101:98cf:af80",
"ospfv3NbrOptions": 19,
"ospfv3NbrPriority": 50,
"ospfv3NbrState": "full",
"ospfv3NbrEvents": 6,
"ospfv3NbrLsRetransQLen": 0,
"ospfv3NbrHelloSuppressed": "false",
"ospfv3NbrIfId": 14,
"ospfv3NbrRestartHelperStatus": "notHelping",
"ospfv3NbrRestartHelperAge": 0,
"ospfv3NbrRestartHelperExitReason": "none",
"context_name": ""
}
],
"count": 1
}

list_ospfv3_ports

List the current OSPFv3 ports.

Route: /api/v0/ospfv3_ports

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/ospfv3_ports
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/ospfv3_ports?hostname=host.example.com

Output:

{
"status": "ok",
 "ospfv3_ports": [
{
"id": 13,
"device_id": 14,
"ospfv3_instance_id": 7,
"ospfv3_area_id": 43,
"port_id": 2390,
"ospfv3IfIndex": 2,
"ospfv3IfInstId": 0,
"ospfv3IfAreaId": 0,
"ospfv3IfType": "broadcast",
"ospfv3IfAdminStatus": "enabled",
"ospfv3IfRtrPriority": 1,
"ospfv3IfTransitDelay": 1,
"ospfv3IfRetransInterval": 5,
"ospfv3IfHelloInterval": 10,
"ospfv3IfRtrDeadInterval": 40,
"ospfv3IfPollInterval": 10,
"ospfv3IfState": "backupDesignatedRouter",
"ospfv3IfDesignatedRouter": "10.0.43.11",
"ospfv3IfBackupDesignatedRouter": "10.7.9.254",
"ospfv3IfEvents": 7,
"ospfv3IfDemand": "false",
"ospfv3IfMetricValue": 10,
"ospfv3IfLinkScopeLsaCount": 2,
"ospfv3IfLinkLsaCksumSum": 64455,
"ospfv3IfDemandNbrProbe": "false",
"ospfv3IfDemandNbrProbeRetransLimit": 0,
"ospfv3IfDemandNbrProbeInterval": 0,
"ospfv3IfTEDisabled": "true",
"ospfv3IfLinkLSASuppression": "false",
"context_name": ""
}
],
"count": 1
}

list_vrf
List the current VRFs.

Route: /api/v0/routing/vrf

Input:

● hostname = Either the devices hostname or id

OR

● vrfname = The VRF name you would like to filter by

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/routing/vrf
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/routing/vrf?hostname=host.example.com
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/routing/vrf?vrfname=Mgmt-vrf

Output:

{
"status": "ok",
"vrfs": [
{
"vrf_id": "2",
"vrf_oid": "8.77.103.109.116.45.118.114.102",
"vrf_name": "Mgmt-vrf",
"mplsVpnVrfRouteDistinguisher": "",
"mplsVpnVrfDescription": "",
"device_id": "8"
},
...
],
"count": 100
}
get_vrf

Retrieves VRF by ID

Route: /api/v0/routing/vrf/:id

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/routing/vrf/2

Output:

{
"status": "ok",
"vrf": [
{
"vrf_id": "2",
"vrf_oid": "8.77.103.109.116.45.118.114.102",
"vrf_name": "Mgmt-vrf",
"mplsVpnVrfRouteDistinguisher": "",
"mplsVpnVrfDescription": "",
"device_id": "8"
}
],
"count": 1
}

list_mpls_services

List MPLS services

Route: /api/v0/routing/mpls/services

Input:
 ● hostname = Either the devices hostname or id

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/routing/mpls/services
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/routing/mpls/services?
hostname=host.example.com

Output:

{
"status": "ok",
"mpls_services": [
{
"svc_id": 1671,
"svc_oid": 27,
"device_id": 4,
"svcRowStatus": "active",
"svcType": "tls",
"svcCustId": 1,
"svcAdminStatus": "up",
"svcOperStatus": "up",
"svcDescription": "",
"svcMtu": 9008,
"svcNumSaps": 1,
"svcNumSdps": 0,
"svcLastMgmtChange": 2,
"svcLastStatusChange": 168,
"svcVRouterId": 0,
"svcTlsMacLearning": "enabled",
"svcTlsStpAdminStatus": "disabled",
"svcTlsStpOperStatus": "down",
"svcTlsFdbTableSize": 250,
"svcTlsFdbNumEntries": 0,
"hostname": "host.example.com"
}
],
"count": 1
}
list_mpls_saps

List MPLS SAPs

Route: /api/v0/routing/mpls/saps

Input:

● hostname = Either the devices hostname or id

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/routing/mpls/saps
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/routing/mpls/saps?
hostname=host.example.com

Output:

{
"status": "ok",
"saps": [
{
"sap_id": 1935,
"svc_id": 1660,
"svc_oid": 7,
"sapPortId": 16108921125,
"ifName": "1/1/c2/1",
"device_id": 3,
"sapEncapValue": "0",
"sapRowStatus": "active",
"sapType": "epipe",
"sapDescription": "",
"sapAdminStatus": "up",
"sapOperStatus": "down",
"sapLastMgmtChange": 2,
"sapLastStatusChange": 0,
 "hostname": "hostname=host.example.com"
}
],
"count": 1

Services

list_services

Retrieve all services

Route: /api/v0/services

Input:

● state: only which have a certain state (valid options are 0=Ok,
1=Warning, 2=Critical).
● type: service type, used sql LIKE to find services, so for tcp, use
type=tcp for http use type=http

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/services
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/services?state=2
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/services?state=0&type=tcp

Output:

{
"status": "ok",
"message": "",
"count": 1,
"services": [
 [
{
"service_id": "13",
"device_id": "1",
"service_ip": "demo1.yourdomian.net",
"service_type": "ntp_peer",
"service_desc": "NTP",
"service_param": "-H 192.168.1.10",
"service_ignore": "0",
"service_status": "0",
"service_changed": "1470962470",
"service_message": "NTP OK: Offset -0.000717 secs",
"service_disabled": "0",
"service_ds": "{\"offset\":\"s\"}"
}
],
[
{
"service_id": "2",
"device_id": "2",
"service_ip": "demo2.yourdomian.net",
"service_type": "esxi_hardware.py",
"service_desc": "vmware hardware",
"service_param": "-H 192.168.1.11 -U USER -P PASS -
p",
"service_ignore": "0",
"service_status": "0",
"service_changed": "1471702206",
"service_message": "OK - Server: Supermicro
X9SCL/X9SCM s/n: 0123456789 System BIOS: 2.2 2015-02-20",
"service_disabled": "0",
"service_ds":
"{\"P2Vol_0_Processor_1_Vcore\":\"\",\"P2Vol_1_System_Board_1_-
12V\":\"\",\"P2Vol_2_System_Board_1_12V\":\"\",\"P2Vol_3_System_Boar
d_1_3.3VCC\":\"\",\"P2Vol_4_System_Board_1_5VCC\":\"\",\"P2Vol_5_Sys
tem_Board_1_AVCC\":\"\",\"P2Vol_6_System_Board_1_VBAT\":\"\",\"P2Vol
_7_System_Board_1_"
}
]
]
}
get_service_for_host

Retrieve services for device

Route: /api/v0/services/:hostname

● id or hostname is the specific device

Input:

● state: only which have a certain state (valid options are 0=Ok,
1=Warning, 2=Critical).
● type: service type, used sql LIKE to find services, so for tcp, use
type=tcp for http use type=http

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/services/:hostname
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/services/:hostname?state=2
curl -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/services/:hostname?state=0&type=tcp

Output:

{
"status": "ok",
"message": "",
"count": 1,
"services": [
[
{
"service_id": "2",
"device_id": "2",
"service_ip": "demo2.yourdomian.net",
"service_type": "esxi_hardware.py",
"service_desc": "vmware hardware",
 "service_param": "-H 192.168.1.11 -U USER -P PASS -
p",
"service_ignore": "0",
"service_status": "0",
"service_changed": "1471702206",
"service_message": "OK - Server: Supermicro
X9SCL/X9SCM s/n: 0123456789 System BIOS: 2.2 2015-02-20",
"service_disabled": "0",
"service_ds":
"{\"P2Vol_0_Processor_1_Vcore\":\"\",\"P2Vol_1_System_Board_1_-
12V\":\"\",\"P2Vol_2_System_Board_1_12V\":\"\",\"P2Vol_3_System_Boar
d_1_3.3VCC\":\"\",\"P2Vol_4_System_Board_1_5VCC\":\"\",\"P2Vol_5_Sys
tem_Board_1_AVCC\":\"\",\"P2Vol_6_System_Board_1_VBAT\":\"\",\"P2Vol
_7_System_Board_1_"
}
]
]
}

add_service_for_host

Add a service for device

Route: /api/v0/services/:hostname

● id or hostname is the specific device

Input:

● type: service type

● ip: ip of the service
● desc: description for the service
● param: parameters for the service
● ignore: ignore the service for checks

Example:

curl -X POST -d '{"type":"ping","ip": "192.168.1.10","desc":"test

ping","param": "-t 10 -c 5"}' -H 'X-Auth-Token: YOURAPITOKENHERE'
https://librenms.org/api/v0/services/192.168.1.10
Output:

{
"status": "ok",
"message": "Service ping has been added to device 192.168.1.10
(#10)"
}

edit_service_from_host

Edits a service

Route: /api/v0/services/:service_id

● service id

Input:

● id: service id

Example:

curl -X PATCH -d '{"service_disabled":"1"}' 'X-Auth-Token:YOUR-API-

TOKEN' https://librenms.org/api/v0/services/5

Output:

{
"status": "ok",
"message": "Service updated successfully"

delete_service_from_host
Deletes service from device

Route: /api/v0/services/:service_id

● service id

Input:

● id: service id

Example:

curl -X DELETE -H 'X-Auth-Token:YOUR-API-TOKEN'

https://librenms.org/api/v0/services/35

Output:

{
"status": "ok",
"message": "Service has been deleted successfully"

Switching

list_vlans

Get a list of all VLANs.

Route: /api/v0/resources/vlans

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/resources/vlans
Output:

{
"status": "ok",
"vlans": [
{
"vlan_id": "31",
"device_id": "10",
"vlan_vlan": "1",
"vlan_domain": "1",
"vlan_name": "default",
"vlan_type": "ethernet",
"vlan_state": 1
},
...
],
"count": 100
}

get_vlans

Get a list of all VLANs for a given device.

Route: /api/v0/devices/:hostname/vlans

● hostname can be either the device hostname or id

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/devices/localhost/vlans

Output:
{
"status": "ok",
"count": 0,
"vlans": [
{
"vlan_vlan": "1",
"vlan_domain": "1",
"vlan_name": "default",
"vlan_type": "ethernet",
"vlan_state": 1
}
]
}

list_links

Get a list of all Links.

Route: /api/v0/resources/links

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/resources/links

Output:

{
"status": "ok",
"links": [
{
"id": 10,
"local_port_id": 100,
"local_device_id": 1,
"remote_port_id": 200,
 "active": 1,
"protocol": "lldp",
"remote_hostname": "host2.example.com",
"remote_device_id": 2,
"remote_port": "xe-0/0/1",
"remote_platform": null,
"remote_version": "Example Router v.1.0"
},
...
],
"count": 100
}

get_links

Get a list of Links per giver device.

Route: /api/v0/devices/:hostname/links

● hostname can be either the device hostname or id

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/devices/localhost/links

Output:

{
"status": "ok",
"links": [
{
"id": 10,
"local_port_id": 100,
"local_device_id": 1,
 "remote_port_id": 200,
"active": 1,
"protocol": "lldp",
"remote_hostname": "host2.example.com",
"remote_device_id": 2,
"remote_port": "xe-0/0/1",
"remote_platform": null,
"remote_version": "Example Router v.1.0"
},
...
],
"count": 10
}

get_link

Retrieves Link by ID

Route: /api/v0/resources/links/:id

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/resources/links/10

Output:

{
"status": "ok",
"links": [
{
"id": 10,
"local_port_id": 100,
"local_device_id": 1,
"remote_port_id": 200,
 "active": 1,
"protocol": "lldp",
"remote_hostname": "host2.example.com",
"remote_device_id": 2,
"remote_port": "xe-0/0/1",
"remote_platform": null,
"remote_version": "Example Router v.1.0"
}
],
"count": 1
}

list_fdb

Get a list of all ports FDB.

Route: /api/v0/resources/fdb/:mac

● mac is the specific MAC address you would like to query

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

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

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"
},
...
],
"count": 100
}

list_fdb_detail

Get a list of all ports FDB with human readable device and interface names.

Route: /api/v0/resources/fdb/:mac/detail

● mac is the specific MAC address you would like to query

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/resources/fdb/1aaa2bbb3ccc/detail

Output:

{
'count': 7,
'mac': '9c:93:aa:bb:cc:dd',
'mac_oui': 'Xerox Corporation',
'ports_fdb': [
{
'hostname': 'hq-core1',
'sysName': 'hq-core1',
'ifName': 'ae10',
 'ifAlias': 'ae10',
'ifDescr': 'ae10',
'last_seen': '2 hours ago',
'updated_at': '2023-05-17 03:19:15'
},
{
'hostname': 'hq-sw1',
'sysName': 'hq-sw1',
'ifName': 'ge-0/0/0',
'ifAlias': 'ge-0/0/0',
'ifDescr': 'ge-0/0/0',
'last_seen': '3 hours ago',
'updated_at': '2023-05-17 02:02:06'
},
...
],
'status': 'ok'
}

list_nac

Get a list of all ports NAC.

Route: /api/v0/resources/nac/:mac

● mac is the specific MAC address you would like to query

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

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

Output:
{
"status": "ok",
"ports_nac": [
{
"ports_nac_id": 1,
"auth_id": "0000000000000AAAABBBB8CC",
"device_id": 3,
"port_id": 6,
"domain": "data",
"username": "hostname.librenms.org",
"mac_address": "1aaa2bbb3ccc",
"ip_address": "192.0.2.2",
"host_mode": "singleHost",
"authz_status": "authorizationSuccess",
"authz_by": "Authentication Server",
"authc_status": "authcSuccess",
"method": "dot1x",
"timeout": "0",
"time_left": "0",
"vlan": 0,
"time_elapsed": null,
"created_at": "2025-05-08T08:55:06.000000Z",
"updated_at": "2025-05-08T08:55:06.000000Z",
"historical": 0
}
]

System

system

Display Librenms instance information.

Route: /api/v0/system

Input:
-

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE'

https://librenms.org/api/v0/system

Output:

{
"status": "ok",
"system": [
{
"local_ver": "1.37-234-g19103ee",
"local_sha": "19103ee36f68f009272c15be22e5a7e10a8b0b85",
"local_date": "1526480966",
"local_branch": "master",
"db_schema": 249,
"php_ver": "7.2.2",
"database_ver": "MariaDB 5.5.56-MariaDB",
"rrdtool_ver": "1.4.8",
"netsnmp_ver": "NET-SNMP 5.7.2"
}
],
"count": 1