del_device

Delete a given device.

Route: /api/v0/devices/:hostname

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

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
        }
    ]
}

get_graphs

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

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

Input:

-

Example:

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

Output:

{
    "status": "ok",
    "err-msg": "",
    "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:

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

Input:

-

Example:

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

Output:

{
    "status": "ok",
    "err-msg": "",
    "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",
    "err-msg": "",
    "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",
    "err-msg": "",
    "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:

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

Input:

-

Example:

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

Output:

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

Example:

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

Output:

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

Example:

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

Output:

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

get_health_graph

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

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

Input:

-

Example:

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

Output:

Output is a stacked graph for the health type provided.

Example:

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

Output:

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

get_wireless_graph

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

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

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

Input:

Example:

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

Output:

Output is an image.

get_port_graphs

Get a list of ports for a particular device.

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

Input:

Example:

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

Output:

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

get_device_ip_addresses

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

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

Example:

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

Output:

{
    "status": "ok",
    "err-msg": "",
    "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

Input:

Example:

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

Output:

{
  "status": "ok",
  "err-msg": "",
  "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_components

Get a list of components for a particular device.

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

Input:

Example:

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

Output:

{
    "status": "ok",
    "err-msg": "",
    "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

Example:

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

Output:

{
    "status": "ok",
    "err-msg": "",
    "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

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",
    "err-msg": "",
    "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

Example:

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

Output:

{
    "status": "ok",
    "err-msg": ""
}

get_port_stats_by_port_hostname

Get information about a particular port for a device.

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

Input:

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

Input:

Example:

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

Output:

Output is an image.

list_devices

Return a list of devices.

Route: /api/v0/devices

Input:

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
  }
 ]
}

add_device

Add a new device.

Route: /api/v0/devices

Input (JSON):

For SNMP v1 or v2c

For SNMP v3

For ICMP only

Example:

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

Output:

{
    "status": "ok",
    "message": "Device localhost.localdomain (57) has been added successfully"
}

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.

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

Input (JSON):

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"
    }
]
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"
    }
]

get_device_groups

List the device groups that a device is matched on.

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

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\" &&"
        }
        ]
    }
]