Introduction

The API is designed to enable you to interact with your installtion from other systems, monitoring systems, apps or websites using any programming language that can make a web request and both send and receive json data. This documentation will provide you the methods, accepted parameters and responses from the API.

Token authentication

Authentication against the API is done by tokens which are assigned to a user account. You can view and create tokens using the API access link within the System > API menu.

To send the token to the API you need to do this by using the X-Auth-Token within the header. As example if your API token was 91c60e737e342c205be5bba8e2954d27 then you would send the following X-Auth-Token: 91c60e737e342c205be5bba8e2954d27. As an example using curl within PHP you would do something like this:

curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-Auth-Token: 91c60e737e342c205be5bba8e2954d27'));

API Responses

The following responses are standard across each request type except for where an image would be returned directly, the response will be output in json format:

status

• ok = The request was successful
• error = The request failed

message

This will contain the reason for the success or failure of the request.

As an example to get you started quickly, here we use the API to request to list all devices:

curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" "https://librenms.example.com/api/v1/list/devices"
{ 
  "status": "ok", 
  "devices": [  
  {
   "device_id": "4",
   "hostname": "example.co.uk",
   "sysName": "example.co.uk",
   "community": "public",
   "authlevel": null,
   "authname": null,
   "authpass": null,
   "authalgo": null,
   "cryptopass": null,
   "cryptoalgo": null,
   "snmpver": "v1",
   "port": "161",
   "transport": "udp",
   "timeout": null,
   "retries": null,
   "bgpLocalAs": null,
   "sysObjectID": null,
   "sysDescr": "Linux example.co.uk 2.6.18-238.19.1.el5 #1 SMP Fri Jul 15 07:31:24 EDT 2011 x86_64",
   "sysContact": "root@localhost",
   "version": "2.6.18-238.19.1.el5",
   "hardware": "Generic x86 64-bit",
   "features": null,
   "location": "Unknown",
   "os": "linux",
   "status": "1",
   "ignore": "0",
   "disabled": "0",
   "uptime": "90741309",
   "agent_uptime": "0",
   "last_polled": "2014-07-16 17:40:04",
   "last_polled_timetaken": "2.16",
   "last_discovered_timetaken": "3.15",
   "last_discovered": "2014-07-16 12:33:44",
   "purpose": "",
   "type": "server",
   "serial": null,
   "icon": null
  },
  {
   "device_id": "24",
   "hostname": "localhost",
   "sysName": "testing",
   "community": "public",
   "authlevel": "noAuthNoPriv",
   "authname": "",
   "authpass": "",
   "authalgo": "MD5",
   "cryptopass": "",
   "cryptoalgo": "AES",
   "snmpver": "v1",
   "port": "161",
   "transport": "udp",
   "timeout": null,
   "retries": null,
   "bgpLocalAs": null,
   "sysObjectID": null,
   "sysDescr": "Linux testing 2.6.32-431.el6.x86_64 #1 SMP Fri Nov 22 03:15:09 UTC 2013 x86_64",
   "sysContact": "root@localhost",
   "version": "2.6.32-431.el6.x86_64",
   "hardware": "Generic x86 64-bit",
   "features": null,
   "location": "Unknown",
   "os": "linux",
   "status": "1",
   "ignore": "0",
   "disabled": "0",
   "uptime": "19355163",
   "agent_uptime": "0",
   "last_polled": "2014-07-16 17:40:04",
   "last_polled_timetaken": "1.74",
   "last_discovered_timetaken": "1.28",
   "last_discovered": "2014-07-16 12:33:25",
   "purpose": null,
   "type": "server",
   "serial": null,
   "icon": null
  }
 ]
}
    

API request types

The following request types are currently used:

• GET - This is used for the retrieval of information or images.
• POST - This is used for adding new items such as devices.
• PUT - This is used to update existing items.
• DELETE - This is used to remove items.

Available requests