REST API Developer's Guide

REST API v2

v2 of LogicMonitor's REST API will allow you to programmatically query and manage your LogicMonitor resources: dashboards, devices, reports, websites, alerts, collectors, datasources, SDTs and more. Comprehensive documentation for available resources and methods can be found here: https://www.logicmonitor.com/swagger-ui-master/dist/. Additional information can be found in the sections below:

General Information about LogicMonitor's REST API:

For general information about LogicMonitor's REST API, including authentication, rate limiting, and versioning information, see this page. Requests will default to v1 of the API, and you can make v2 requests by including a '?v=2' query parameter or by including a 'X-Version:2' header.

v2 Changes:

Compared to v1, v2 has many changes (including non-backwards compatible changes). The following is a list of major differences, but please look at v2 methods and resources for more details:

  • Status codes - In v1 of the API, there were two status codes for a response: HTTP status code (almost always 200), and a different LM status code in the response body. With v2, we're returning one HTTP status code, and we've considerably narrowed the list of possible status codes that will be returned. This change was made to ensure that response codes are as meaningful and actionable as possible.
  • Response body structure - In v1 of the API, successful responses included 'status', 'errmsg', and 'data' objects at the top level of the response. With v2, since the HTTP status now matches the LM status, the contents of 'data' will be returned at the top level for a successful response. A non-successful response will include error message fields. Note that this does mean that scripts written for v1 of the API and configured to parse API response should be adjusted to reflect this. Here's an example of before and after:
v1 (before):
HTTP 200 
Response Body:
{ 
"status":200, 
"errmsg":"OK", 
"data": { 
     "id":34, 
     "name":"Prod Server 1" 
 } 
}
v2 (after):
HTTP 200
Response Body:
{
     "id":34,
     "name":"Prod Server 1"
}
  • No Basic authentication support - We've removed support for Basic authentication with v2 of the API. We did this to encourage more use of API tokens for authentication, as there are many additional benefits (separation of UI / API access, audit log entries, more secure). 
  • Support for PATCH - v2 includes support for HTTP PATCH for most resources. You may find this useful for updating just one field of a resource, instead of having to use PUT to update the entire resource (all fields).  You can determine whether PATCH is supported for a given resource by checking the documentation here: https://www.logicmonitor.com/swagger-ui-master/dist/
  • Filter syntax - Filter query parameter values should be enclosed in double quotes in v2. This change was made to better accommodate filters that include special characters. E.g. GET /device/devices?filter=name:"Prod-Server-123"

 

Status Codes

When an unsuccessful request is made, the response body will contain an ‘errorCode’ field with one of the following codes:

HTTP Status Code API v2 Error Code Description
202 1202 The request has been accepted for processing, but the processing has not been completed
400 1400 Bad request (e.g. a resource cannot be deleted because something else is dependent on it)
401 1401  Authentication failed
403  1403  Authentication succeeded; Permission denied
404  1404  No such resource
409  1409  The resource already exists
412  1412  A precondition was not met (e.g. two factor authentication)
413  1413  Request entity too large (e.g. the report is too large to be generated)
429  1429 Too many requests (exceeded rate limits) 
500  1500 Internal error

 

Examples

GET /device/devices?v=2&fields=name,id&size=2
HTTP 200
Response Body:
{
"total": 222,
"items": [
{
"id": 3,
"name": "ilo-mx233700hu.usa.lab"
},
{
"id": 5,
"name": "idrac-r610.csc.lab"
}
],
"searchId": null,
"isMin": false
}
GET /device/devices?v=2&fields=name,id&size=2 
HTTP 404
Response Body:
{
"errorMessage": "Authentication failed",
"errorCode": 1401,
"errorDetail": null
}