Checks API

Reference documentation

The /checks API endpoint

/checks (GET)

The /checks API endpoint provides HTTP GET access to subscription check data.

NOTE: GET /checks responses do not include checks that are configured as standalone checks.

EXAMPLE

The following example demonstrates a request to the /checks API, resulting in a JSON Array of JSON Hashes containing subscription check definitions.

$ curl -s http://127.0.0.1:4567/checks | jq .
[
  {
    "name": "sensu_website",
    "interval": 60,
    "subscribers": [
      "production"
    ],
    "command": "check-http.rb -u https://sensuapp.org"
  }
]

API Specification

/checks (GET)
description Returns the list of checks.
example url http://hostname:4567/checks
pagination see pagination
response type Array
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output 
[
  {
    "name": "chef_client_process",
    "command": "check-procs.rb -p /usr/bin/chef-client -W 1 -w 2 -c 3",
    "subscribers": [
      "production"
    ],
    "interval": 60
  },
  {
     "name": "website",
    "command": "check-http.rb -h localhost -p /health -P 80 -q Passed -t 30",
    "subscribers": [
      "webserver"
    ],
    "interval": 30
  }
]

The /checks/:check API endpoint(s)

/checks/:check (GET)

The /checks/:check API endpoints provide HTTP GET access to subscription check data for specific :check definitions, by check name.

EXAMPLE

In the following example, querying the /checks/:check API returns a JSON Hash containing the requested :check definition (i.e. for the :check named sensu_website).

$ curl -s http://127.0.0.1:4567/checks/sensu_website | jq .
{
  "name": "sensu_website",
  "interval": 60,
  "subscribers": [
    "production"
  ],
  "command": "check-http.rb -u https://sensuapp.org"
}

The following example demonstrates a request for check data for a non-existent :check named non_existent_check, which results in a 404 (Not Found) HTTP response code (i.e. HTTP/1.1 404 Not Found).

$ curl -s -i http://127.0.0.1:4567/checks/non_existent_check

HTTP/1.1 404 Not Found
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
Content-Length: 0
Connection: keep-alive
Server: thin

API Specification

/checks/:check (GET)
description Returns a check.
example url http://hostname:4567/checks/sensu_website
response type Hash
response codes
  • Success: 200 (OK)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)
output 
{
  "name": "chef_client_process",
  "command": "check-procs.rb -p /usr/bin/chef-client -W 1 -w 2 -c 3",
  "subscribers": [
    "production"
  ],
  "interval": 60
}

/checks/:check (DELETE)

The /checks/:check endpoint provides HTTP DELETE access to check results and history.

EXAMPLE

The following example demonstrates a request to delete a check named sensu_website, resulting in a 202 (Accepted) HTTP response code and and a JSON Hash containing an issued timestamp.

$ curl -s -i -X DELETE http://127.0.0.1:4567/checks/sensu_website

HTTP/1.1 202 Accepted
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
Content-Length: 21
Connection: keep-alive
Server: thin

{"issued":1539627787}

API Specification

/checks/:check (DELETE)
description Asynchronously removes check results and check history for a specified check across all clients. This endpoint does not modify any configuration files.
example url http://hostname:4567/checks/sensu_website
response codes
  • Success: 202 (Accepted)
  • Error: 500 (Internal Server Error)
output 
HTTP/1.1 202 Accepted
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
Content-Length: 21
Connection: keep-alive
Server: thin

{"issued":1539627787}

The /request API endpoint

/request (POST)

The /request API provides HTTP POST access to publish subscription check requests via the Sensu API.

EXAMPLE

In the following example, an HTTP POST is submitted to the /request API, requesting a check execution for the sensu_website subscription check, resulting in a 202 (Accepted) HTTP response code (i.e. HTTP/1.1 202 Accepted) and a JSON Hash containing an issued timestamp.

curl -s -i \
-X POST \
-H 'Content-Type: application/json' \
-d '{"check": "sensu_website"}' \
http://127.0.0.1:4567/request

HTTP/1.1 202 Accepted
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
Content-Length: 21
Connection: keep-alive
Server: thin

{"issued":1460142533}

PRO TIP: the /request API can be a powerful utility when combined with check definitions that are configured with "publish": false (i.e. checks which are not intended to run on a scheduled interval). Using "publish": false along with the /request API makes it possible to request predefined check executions on an as-needed basis.

The following example demonstrates a request for a check execution for a non-existent check named non_existent_check, which results in a 404 (Not Found) HTTP response code (i.e. HTTP/1.1 404 Not Found).

curl -s -i \
-X POST \
-H 'Content-Type: application/json' \
-d '{"check": "non_existent_check"}' \
http://127.0.0.1:4567/request

HTTP/1.1 404 Not Found
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
Content-Length: 0
Connection: keep-alive
Server: thin

API Specification

/request (POST)
description Issues a check execution request.
example url http://hostname:4567/request
payload 
{
  "check": "chef_client_process",
  "subscribers": [
    "production"
  ],
  "creator": "sysop@example.com",
  "reason": "triggered application deployment"
}
_NOTE: the subscribers attribute is not required for requesting a check execution, however it may be provided to override the subscribers check definition attribute._ NOTE: the creator and reason attributes are not required for requesting a check execution, however they may be provided to add more context to the check request and in turn the check result(s). The check request creator and reason are added to the check request payload under api_requested.
response codes
  • Success: 202 (Accepted)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)