Sensu Checks API

Reference documentation

The /checks API endpoint

/checks (GET)

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

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)
desc.
Returns the list of checks.
example url
http://hostname:4567/checks
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 subcription 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)
desc.
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
}

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)
desc.
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)

Start your FREE trial today.

Already using Sensu Core? Upgrade to Sensu Enterprise today to take advantage of its enterprise console, added-value features, built-in integrations, FREE annual training, and enterprise-class support.