RPC API Developer's Guide

Using LogicMonitor's RPC API

Note that LogicMonitor's RPC API has been deprecated - it will remain available until December 1, 2017 for existing accounts where it is already in use, but it is not available to new accounts and will not be updated/improved moving forward. As such, we highly recommend using LogicMonitor's REST API where possible.  In addition to offering more coverage in most areas of the product, our REST API includes a more secure authentication method and a more consistent syntax that meets RESTful standards.  Additionally, note that use of LogicMonitor's old Puppet Module counts as use of the RPC API, and should be replaced with LogicMonitor's newer, REST API based, Puppet Module.  Please see the table at the bottom of the page for a 1:1 mapping between RPC functions and REST resources.


The LogicMonitor RPC API enables you to programmatically query and manage your LogicMonitor resources.  All RPCs use HTTP as the transport protocol and are in the format of companyname.logicmonitor.com/santaba/rpc/funcname. To begin using LogicMonitor's developer API you will need:

  • A terminal to make a generic HTTP request OR
  • A web browser OR
  • A (command line) tool to send and receive HTTPS requests e.g. cURL OR
  • A programming language or library for sending/receiving HTTPS requests e.g. the net/https library for Ruby

Any API calls not documented in LogicMonitor's RPC & REST Developer Guides are considered unpublished.  We advise against using unpublished API calls as they are subject to change without notice, use of them will likely result in scripts breaking & LogicMonitor's Technical Support will be unable to assist you with any issues you encounter.  

 

Resources

You can use the RPC API to manage:

Looking for more?  Check out the published resources of LogicMonitor's new REST API.

 

Structure of RPC Requests & Responses

RPC requests should be made to the following URL:  https://ACCOUNTNAME.logicmonitor.com/santaba/rpc/functionName

Where ACCOUNTNAME should be replaced with your LogicMonitor account name and functionName should be replaced with the RPC API call name (e.g. getHosts, addOpsNote, getAlerts, etc.).  Note that RPC API calls are case sensitive.

All parameters included in the request should be appended onto the end of the URL as query arguments like this: https://ACCOUNTNAME.logicmonitor.com/santaba/rpc/APICALL?parameter1=value1¶meter2=value2¶meter3=value3

Parameters that are required to be or can optionally be included in RPC requests can be found on the document specific to that call.

All RPC responses are JSON, and have the following object structure:

{ [status], [data], [errmsg] }

Where status indicates if the request is served correctly or why the rest failed, data is the data included in the response and errmsg provides a description about any errors for failed requests.  The contents of the data object varies depending on the RPC API request made (i.e. the data returned for getAlerts is different from the data returned by addOpsNote).

 

Authenticating Requests

Each request sent to the LogicMonitor server must be made over HTTPS, and must also be authenticated.  The LogicMonitor server uses one of two approaches to authenticate RPC requests:

  • CUP
  • Session

The account being used must be a LogicMonitor created account, not a SAML account.  LogicMonitor enforces the use of CUP-based authentication for API calls that can change data or configuration.  This enforcement is to protect against cross-site request forgery (CSRF) attacks.  Session-based authentication remains valid for read-based commands.

 

CUP Authentication

A LogicMonitor account name, username, and password are included in the query string for each RPC request.

Example GET request:

GET /santaba/rpc/getEscalatingChains?c=accountName&u=username&p=password HTTP/1.1 ... ...

 

Example curl command:

curl "http://www.accountName.logicmonitor.com/santaba/rpc/getEscalatingChains?c=accountName&u=username&p=password"

 

Property

Description

c Company(Account) name. This is the name in your LogicMonitor URL: https://ACCOUNTNAME.logicmonitor.com
u LogicMonitor username. This is the username associated with your LogicMonitor account.
p LogicMonitor password. This password needs to correspond to the username specified.

 

Session Based Authentication

If a user's application supports cookies, they can use session-based authentication for read-only RPC API calls (i.e. RPC API calls that do not add, update, or delete).  In this approach, the application calls /santaba/rpc/signIn first. The server will create a session object for the user and put the session ID in the cookie. Before the application exits, it can call /santaba/rpc/signOut. The session will time out if there are no calls for 30 minutes.

Example GET request:

Sign In:
GET /santaba/rpc/signIn?c=accountName&u=username&p=password HTTP/1.1 ... ...
  Response:
 

HTTP/1.1 200 OK

Set-Cookie: SESSIONID=xxxxxxxx

  Subsequent Request:
GET /santaba/rpc/signIn?c=accountName&u=username&p=password HTTP/1.1 

Cookie: SESSIONID=xxxxxx

  Sign Out:
GET /santaba/rpc/signOut HTTP/1.1 

 

Example curl command (2 ways):

Save cookie information in a text file:

curl -c cookies.txt -d "c=accountName&u=username&p=password" "https://accountName.logicmonitor.com/santaba/rpc/signIn"

Once we have the cookie from that session stored in "cookies.txt" we can use that file to authenticate subsequent calls:

curl -b cookies.txt -v "https://accountName.logicmonitor.com/santaba/rpc/getEscalatingChains"
 

Grab JSESSIONID from a curl command:

curl -v "https://accountName.logicmonitor.com/santaba/rpc/signIn?c=accountName&u=username&p=password"

From the output of the above command, grab the JSESSIONID value and use it in subsequent calls:

curl -v --cookie "JSESSIONID=jsession_cookie_value" "https://accountName.logicmonitor.com/santaba/rpc/getEscalatingChains"

 

Getting Started

Interaction with LogicMonitor's API is straightforward. You send a HTTP request (GET or POST) with the required parameters and LogicMonitor will return a HTTP response with the requested data.

1.) An Example: Getting a list of devices in LogicMonitor

> GET /santaba/rpc/getHosts?hostGroupId=1 HTTP/1.1
> Host: demo.logicmonitor.com
> Accept: */*
> 
< HTTP/1.1 200 OK
< Content-Type: text/plain;charset=utf-8
< Transfer-Encoding: chunked
< Date: Tue, 15 Jan 2013 21:04:39 GMT
{
  "status": 200,
  "data": {
    "hostgroup": {
      "alertEnable": true,
      "createdOn": 0,
      "id": 1,
      "parentId": 0,
      "description": "",
      "appliesTo": "",
      "name": "demo",
      "properties": {
        "tomcat.jmxports": "9000",
        "jmx.port": "9000",
        "mongodb.ports": "12345"
      },
      "fullPath": ""
    },
    "hosts": [
      {
        "netflowAgentId": 0,
        "displayedAs": "10.0.0.25",
        "status": "alert-noconfirmed",
        "link": "",
        "agentDescription": "VCENTER",
        "agentId": 17,
        "properties": {
          "system.virtualization": "",
          "tomcat.jmxports": "9003",
          "snmp.version": "v2c",
          "system.hostname": "10.0.0.25",
          "system.sysinfo": "NetApp Release 7.3.2: Thu Oct 15 03:13:41 PDT 2009",
          "system.categories": "snmpTCPUDP,NetApp",
          "system.db.mysql": "",
          "system.groups": "x Storage/East Coast",
          "system.sysoid": "1.3.6.1.4.1.789.2.1",
          "system.db.mssql": "",
          "jmx.port": "9003",
          "system.db.oracle": "",
          "system.displayname": "10.0.0.25",
          "mongodb.ports": "27018",
          "system.ips": "10.0.0.25,10.0.0.22"
        },
        "inSDT": false,
        "type": "HOST",
        "scanConfigId": 0,
        "effectiveAlertEnabled": true,
        "id": 205,
        "createdOn": 1342561458,
        "alertEnable": true,
        "isActive": false,
        "fullPathInIds": [
          7,
          70
        ],
        "autoPropsUpdatedOn": 1358220726,
        "description": "",
        "name": "10.0.0.25",
        "hostName": "10.0.0.25",
        "autoPropsAssignedOn": 1358220721,
        "updatedOn": 1358277325,
        "enableNetflow": false
      },
      ... ...
   ]
  },
  "errmsg": "OK"
}

 

2.) The same example using your browser via this URL: "https://accountName.logicmonitor.com/santaba/rpc/getHosts?hostGroupId=hostGroupId&c=accountName&u=username&p=password"

 

3.) The same example using cURL  curl -v "https://accountName.logicmonitor.com/santaba/rpc/getHosts?hostGroupId=hostGroupId&c=accountName&u=username&p=password"

 

4.) The same example using Ruby:

#
# Purpose:
#   Add abstraction and simplify the building of URL's,
#   send and receive HTTPS requests (specifically RPC calls to LogicMonitor's API)
#
# Parameters: to be used in your request
#   Authentication - 
#      (String) c = accountName
#      (String) u = username
#      (String) p = password
#   (String) URL -
#      The URL to invoke the RPC and HTTPS request
#
require 'net/http'
require 'net/https'

if ARGV.length == 3
  company = ARGV[0]
  user = ARGV[1]
  password = ARGV[2]
else
  puts "Usage: ruby apirequest.rb ACCOUNTNAME USERNAME PASSWORD"
  return -1
end

url = "https://#{accountName}.logicmonitor.com/santaba/rpc/getHosts?
   hostGroupId=1&c=#{accountName}&u=#{username}&p=#{password}"
uri = URI(url)
http = Net::HTTP.new(uri.host, 443)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
req = Net::HTTP::Get.new(uri.request_uri)
response = http.request(req)
puts response.body
4.1) The same example using Python 
#!/usr/bin/python
#
# basic_api_call.py
# Purpose:
#   Add abstraction and simplify the building of URL's,
#   send and receive HTTPS requests (specifically RPC calls to LogicMonitor's API)
#
# Parameters:
#   Authentication - 
#      (String) c = accountName
#      (String) u = username
#      (String) p = password
#   (String) call -
#      The RPC to invoke
#   (Dictionary) params -
#      A dictionary of the parameters to be used in the API call
#      e.g {"property1": "value1", "integerProperty": 12345}
#

import urllib
import urlparse

company = "ACCOUNTNAME"
user = "USER"
password = "PASSWORD"

def rpc(action, params):
    """Make a call to the LogicMonitor RPC library and return the response"""
    print "Calling action: %s" % action
    print "Parameters: %s" % str(params)
    param_str = urllib.urlencode(params)
    creds = urllib.urlencode({"c": company, "u": user, "p": password})
    if param_str:
        param_str = param_str + "&"
    param_str = param_str + creds
    try:
        f = urllib.urlopen("https://{0}.logicmonitor.com/santaba/rpc/{1}?{2}".format(company, action, param_str))
        return f.read()
    except IOError as ioe:
        print ioe
    #end try
#end rpc

rpc("getHosts", {"hostGroupId": 1})

 

RPC & REST equivalents:

RPC

REST

addOpsNote https://www.logicmonitor.com/support/rest-api-developers-guide/ops-notes/add-opsnotes/
getAlerts https://www.logicmonitor.com/support/rest-api-developers-guide/alerts/get-alerts/
confirmAlerts https://www.logicmonitor.com/support/rest-api-developers-guide/alerts/acknowledge-alerts/
getData https://www.logicmonitor.com/support/rest-api-developers-guide/data/get-data/
getGraphData https://www.logicmonitor.com/support/rest-api-developers-guide/data/get-graph-data/
getGraphImage --download via UI--
addAgent https://www.logicmonitor.com/support/rest-api-developers-guide/collectors/add-a-collector/
getAgent(s) https://www.logicmonitor.com/support/rest-api-developers-guide/collectors/get-collectors/
updateAgent https://www.logicmonitor.com/support/rest-api-developers-guide/collectors/update-a-collector/
deleteAgent https://www.logicmonitor.com/support/rest-api-developers-guide/collectors/delete-a-collector/
getDashboards https://www.logicmonitor.com/support/rest-api-developers-guide/dashboards/get-dashboards/
createDashboard https://www.logicmonitor.com/support/rest-api-developers-guide/dashboards/add-a-dashboard/
updateDashboard https://www.logicmonitor.com/support/rest-api-developers-guide/dashboards/update-a-dashboard/
deleteDashboard https://www.logicmonitor.com/support/rest-api-developers-guide/dashboards/delete-a-dashboard/
getWidgets https://www.logicmonitor.com/support/rest-api-developers-guide/dashboards/get-widgets/
cloneWidget

https://www.logicmonitor.com/support/rest-api-developers-guide/dashboards/get-widgets/

+

https://www.logicmonitor.com/support/rest-api-developers-guide/dashboards/add-a-widget/

deleteWidget https://www.logicmonitor.com/support/rest-api-developers-guide/dashboards/delete-a-widget/
getEscalatingChains https://www.logicmonitor.com/support/rest-api-developers-guide/escalation-chains/get-escalation-chains/
addEscalatingChain https://www.logicmonitor.com/support/rest-api-developers-guide/escalation-chains/add-escalation-chains/
updateEscalatingChain https://www.logicmonitor.com/support/rest-api-developers-guide/escalation-chains/update-escalation-chains/
deleteEscalatingChain https://www.logicmonitor.com/support/rest-api-developers-guide/escalation-chains/delete-escalation-chains/
addHost https://www.logicmonitor.com/support/rest-api-developers-guide/devices/add-a-device/
getHost(s) https://www.logicmonitor.com/support/rest-api-developers-guide/devices/get-devices/
updateHost https://www.logicmonitor.com/support/rest-api-developers-guide/devices/update-a-device/
verifyProperties https://www.logicmonitor.com/support/rest-api-developers-guide/devices/get-devices/#Example-Request-5--GET-all-devices-that-have-a-spe
getDataSourceInstances https://www.logicmonitor.com/support/rest-api-developers-guide/datasource-instances/get-datasource-instances/
deleteHost https://www.logicmonitor.com/support/rest-api-developers-guide/devices/delete-a-device/
getHostProperties https://www.logicmonitor.com/support/rest-api-developers-guide/devices/get-device-properties/
addHostGroup https://www.logicmonitor.com/support/rest-api-developers-guide/device-groups/add-a-device-group/
getHostGroup(s) https://www.logicmonitor.com/support/rest-api-developers-guide/device-groups/get-device-groups/
updateHostGroup https://www.logicmonitor.com/support/rest-api-developers-guide/device-groups/update-a-device-group/
deleteHostGroup https://www.logicmonitor.com/support/rest-api-developers-guide/device-groups/delete-a-device-group/
getHostGroupProperties https://www.logicmonitor.com/support/rest-api-developers-guide/device-groups/get-device-group-properties/
addAccount https://www.logicmonitor.com/support/rest-api-developers-guide/users/add-users/
getAccountProfile https://www.logicmonitor.com/support/rest-api-developers-guide/users/get-users/
updateAccount https://www.logicmonitor.com/support/rest-api-developers-guide/users/update-users/
deleteAccount https://www.logicmonitor.com/support/rest-api-developers-guide/users/delete-users/
getRole(s) https://www.logicmonitor.com/support/rest-api-developers-guide/roles/get-roles/
getSDTs https://www.logicmonitor.com/support/rest-api-developers-guide/sdts/get-sdts/
addSDTs https://www.logicmonitor.com/support/rest-api-developers-guide/sdts/add-sdts/
deleteSDTs https://www.logicmonitor.com/support/rest-api-developers-guide/sdts/delete-sdts/


Rate Limiting

Effective version 100 of the LogicMonitor application, rate limits will be imposed for requests to LogicMonitor's RPC API. Limits will be per method. For example, requests to /rpc/getData may have a different limit from requests to /rpc/getAlerts. Requests that are made in excess of the rate limits will get an HTTP 429 Too Many Requests. Limits are not per user, and will apply to all requests made for your account.

Effective version 99, information about limits and proximity to limits is returned in the below response headers. This enables you to view the rate limits that will be imposed and adjust scripts as needed to work around them. For example, you may introduce logic in your script that, when rate limits have been met, waits 60 seconds before making another request. 

Header

Description

X-Rate-Limit-Limit

Request limit per X-Rate-Limit-Window

X-Rate-Limit-Remaining

The number of requests left for the time window

X-Rate-Limit-Window

The rolling time window length with the unit of second

 We recommend basing any logic intended to work around rate limiting on the above headers and their values, as the limits are subject to change.