Checks API

The /checks API endpoint

/checks (GET)

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

EXAMPLE

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

curl -H "Authorization: Bearer TOKEN" http://127.0.0.1:8080/api/core/v2/namespaces/default/checks

HTTP/1.1 200 OK
[
  {
    "command": "check-cpu.sh -w 75 -c 90",
    "handlers": [
      "slack"
    ],
    "interval": 60,
    "publish": true,
    "subscriptions": [
      "linux"
    ],
    "metadata": {
      "name": "check-cpu",
      "namespace": "default"
    }
  }
]

API Specification

/checks (GET)
description Returns the list of checks.
example url http://hostname:8080/api/core/v2/namespaces/default/checks
response type Array
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output
[
  {
    "command": "check-cpu.sh -w 75 -c 90",
    "handlers": [
      "slack"
    ],
    "interval": 60,
    "publish": true,
    "subscriptions": [
      "linux"
    ],
    "metadata": {
      "name": "check-cpu",
      "namespace": "default"
    }
  },
  {
    "command": "http_check.sh https://sensu.io",
    "handlers": [
      "slack"
    ],
    "interval": 15,
    "proxy_entity_name": "sensu.io",
    "publish": true,
    "subscriptions": [
      "site"
    ],
    "metadata": {
      "name": "check-sensu-site",
      "namespace": "default"
    }
  }
]

/checks (POST)

EXAMPLE

In the following example, an HTTP POST request is submitted to the /checks API to create a check-cpu check. The request includes the check definition in the request body and returns a successful HTTP 200 OK response and the created check definition.

curl -X POST \
-H "Authorization: Bearer TOKEN" \
-H 'Content-Type: application/json' \
-d '{
  "command": "check-cpu.sh -w 75 -c 90",
  "subscriptions": [
    "linux"
  ],
  "interval": 60,
  "publish": true,
  "handlers": [
    "slack"
  ],
  "metadata": {
    "name": "check-cpu",
    "namespace": "default"
  }
}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/checks

HTTP/1.1 200 OK
{
  "command": "check-cpu.sh -w 75 -c 90",
  "subscriptions": [
    "linux"
  ],
  "interval": 60,
  "publish": true,
  "handlers": [
    "slack"
  ],
  "metadata": {
    "name": "check-cpu",
    "namespace": "default"
  }
}

API Specification

/checks (POST)
description Create a Sensu check.
example URL http://hostname:8080/api/core/v2/namespaces/default/checks
example payload
{
  "command": "check-cpu.sh -w 75 -c 90",
  "subscriptions": [
    "linux"
  ],
  "interval": 60,
  "publish": true,
  "handlers": [
    "slack"
  ],
  "metadata": {
    "name": "check-cpu",
    "namespace": "default"
  }
}
payload parameters Required check attributes: command (string), subscriptions (array of strings), interval (integer) OR cron (string), publish (set to true), and a metadata scope containing name (string) and namespace (string). For more information about creating checks, see the check reference.
response codes
  • Success: 200 (OK)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

The /checks/:check API endpoint

/checks/:check (GET)

The /checks/:check API endpoint provides HTTP GET access to check data for specific :check definitions, by check name.

EXAMPLE

In the following example, querying the /checks/:check API returns a JSON Map containing the requested :check definition (in this example: for the :check named check-cpu).

curl -H "Authorization: Bearer TOKEN" \
http://127.0.0.1:8080/api/core/v2/namespaces/default/checks/check-cpu 

HTTP/1.1 200 OK
{
  "command": "check-cpu.sh -w 75 -c 90",
  "handlers": [
    "slack"
  ],
  "interval": 60,
  "publish": true,
  "subscriptions": [
    "linux"
  ],
  "metadata": {
    "name": "check-cpu",
    "namespace": "default"
  }
}

API Specification

/checks/:check (GET)
description Returns a check.
example url http://hostname:8080/api/core/v2/namespaces/default/checks/check-cpu
response type Map
response codes
  • Success: 200 (OK)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)
output
{
  "command": "check-cpu.sh -w 75 -c 90",
  "handlers": [
    "slack"
  ],
  "interval": 60,
  "publish": true,
  "subscriptions": [
    "linux"
  ],
  "metadata": {
    "name": "check-cpu",
    "namespace": "default"
  }
}

/checks/:check (PUT)

API Specification

/checks/:check (PUT)
description Create or update a Sensu check.
example URL http://hostname:8080/api/core/v2/namespaces/default/checks/check-sensu-site
payload
{
  "command": "http_check.sh https://sensu.io",
  "handlers": [
    "slack"
  ],
  "interval": 15,
  "proxy_entity_name": "sensu.io",
  "publish": true,
  "subscriptions": [
    "site"
  ],
  "metadata": {
    "name": "check-sensu-site",
    "namespace": "default"
  }
}
response codes
  • Success: 201 (Created)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

/checks/:check (DELETE)

API Specification

/checks/:check (DELETE)
description Removes a check from Sensu given the check name.
example url http://hostname:8080/api/core/v2/namespaces/default/checks/check-cpu
response codes
  • Success: 202 (Accepted)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)

The /checks/:check/execute API endpoint

/checks/:check/execute (POST)

The /checks/:check/execute API endpoint provides HTTP POST access to create an ad-hoc check execution request, allowing you to execute a check on demand.

EXAMPLE

In the following example, an HTTP POST request is submitted to the /checks/:check/execute API to execute the check-sensu-site check. The request includes the check name in the request body and returns a successful HTTP 202 Accepted response and an issued timestamp.

curl -X POST \
-H "Authorization: Bearer TOKEN" \
-H 'Content-Type: application/json' \
-d '{"check": "check-sensu-site"}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/checks/check-sensu-site/execute

HTTP/1.1 202 Accepted
{"issued":1543861798}

API Specification

/checks/:check/execute (POST)
description Creates an adhoc request to execute a check given the check name.
example URL http://hostname:8080/api/core/v2/namespaces/default/checks/check-sensu-site/execute
payload
{"check": "check-sensu-site"}
payload parameters check (required): the name of the check to execute
response codes
  • Success: 200 (OK)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

The /checks/:check/hooks/:type/hook/:hook API endpoint

/checks/:check/hooks/:type/hook/:hook (DELETE)

This endpoint provides HTTP DELETE access to a hook assigned to a check.

EXAMPLE

The following example shows a request to remove the process-tree hook from the check-cpu check, resulting in a successful HTTP 204 No Content response.

curl -X DELETE \
-H "Authorization: Bearer TOKEN" \
http://127.0.0.1:8080/api/core/v2/namespaces/default/checks/check-cpu/hooks/critical/hook/process_tree 

HTTP/1.1 204 No Content

API Specification

/checks/:check/hooks/ :type/hook/:hook (DELETE)
description Removes a single hook from a check given the check name, hook type, and hook name. See the hooks reference for available types.
example url http://hostname:8080/api/core/v2/namespaces/default/checks/check-cpu/hooks/critical/hook/process-tree
response codes
  • Success: 204 (No Content)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)