RESTful API Overview

Sensu API

The Sensu API provides access to monitoring data collected by Sensu, such as a client registry, check results, and event data. The API can be used to request adhoc check executions, and resolve events, among other things.

RESTful JSON API

The Sensu API is JSON-based RESTful API. Familiarity with (or willingness to Google) industry standard RESTful API behaviors – including HTTP response codes – are strongly recommended.

Reference documentation

Response Content Filtering

Sensu API endpoints that support the GET HTTP method support HTTP response content filtering on one or more Sensu attributes. To use response content filtering, construct the URL for your API request using a dot notation query beginning with filter.

For example, to return only events that match the production environment and ops contact, use the following request.

curl -i 'http://127.0.0.1:4567/events?filter.client.environment=production&filter.check.contact=ops'

Response filtering is only available for string values; integers (for example: filter.check.status=2) are not supported.

Response Content Pagination

By default, the Sensu API will return all available results, but sometimes this result can be massive. To paginate the returned result, the limit and offset query string parameters can be used. This method also sets the “X-Pagination” HTTP response header to a JSON object containing the limit, offset, and total number of items that are being paginated.

parameters description
limit The number of items to return
offset The number of items to offset before returning.

Examples

The following example demonstrates a /clients API query with limit=1 and offset=1. 

$ curl -i 'http://127.0.0.1:4567/clients?limit=1&offset=1'

HTTP/1.1 200 OK
Content-type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
Connection: close
X-Pagination: {"limit":1,"offset":1,"total":848}

[
  {
    "name": "client-02",
    "address": "127.0.0.1",
    "subscriptions": [],
    "timestamp": 1538843586
  }
]