Checks API
NOTE: Requests to the checks API require you to authenticate with a Sensu access token or API key.
The code examples in this document use the environment variable $SENSU_API_KEY
to represent a valid API key in API requests.
Get all checks
The /checks
API endpoint provides HTTP GET access to check data.
Example
The following example demonstrates a request to the /checks
API endpoint, resulting in a JSON array that contains check definitions.
curl -X GET \
http://127.0.0.1:8080/api/core/v2/namespaces/default/checks \
-H "Authorization: Key $SENSU_API_KEY"
HTTP/1.1 200 OK
[
{
"command": "check-email.sh -w 75 -c 90",
"handlers": [
"slack"
],
"high_flap_threshold": 0,
"interval": 60,
"low_flap_threshold": 0,
"publish": true,
"runtime_assets": null,
"subscriptions": [
"linux"
],
"proxy_entity_name": "",
"check_hooks": null,
"stdin": false,
"subdue": null,
"ttl": 0,
"timeout": 0,
"round_robin": false,
"output_metric_format": "",
"output_metric_handlers": null,
"output_metric_tags": null,
"env_vars": null,
"metadata": {
"name": "check-email",
"namespace": "default",
"created_by": "admin"
}
}
]
API Specification
/checks (GET) | |
---|---|
description | Returns the list of checks. |
example url | http://hostname:8080/api/core/v2/namespaces/default/checks |
pagination | This endpoint supports pagination using the limit and continue query parameters. |
response filtering | This endpoint supports API response filtering. |
response type | Array |
response codes |
|
output |
|
Create a new check
The /checks
API endpoint provides HTTP POST access to create checks.
Example
In the following example, an HTTP POST request is submitted to the /checks
API endpoint 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: Key $SENSU_API_KEY" \
-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 201 Created
API Specification
/checks (POST) | |
---|---|
description | Creates a Sensu check. |
example URL | http://hostname:8080/api/core/v2/namespaces/default/checks |
example payload |
|
payload parameters | Required check attributes: interval (integer) or cron (string) and a metadata scope that contains name (string) and namespace (string). For more information about creating checks, see the check reference. |
response codes |
|
Get a specific check
The /checks/:check
API endpoint provides HTTP GET access to check data for :check
definitions, specified by check name.
Example
In the following example, querying the /checks/:check
API endpoint returns a JSON map that contains the requested :check
definition (in this example, for the :check
named check-cpu
).
curl -X GET \
http://127.0.0.1:8080/api/core/v2/namespaces/default/checks/check-cpu \
-H "Authorization: Key $SENSU_API_KEY"
HTTP/1.1 200 OK
{
"command": "check-cpu.sh -w 75 -c 90",
"handlers": [
"slack"
],
"high_flap_threshold": 0,
"interval": 60,
"low_flap_threshold": 0,
"publish": true,
"runtime_assets": null,
"subscriptions": [
"linux"
],
"proxy_entity_name": "",
"check_hooks": null,
"stdin": false,
"subdue": null,
"ttl": 0,
"timeout": 0,
"round_robin": false,
"output_metric_format": "",
"output_metric_handlers": null,
"output_metric_tags": null,
"env_vars": null,
"metadata": {
"name": "check-cpu",
"namespace": "default",
"created_by": "admin"
}
}
API Specification
/checks/:check (GET) | |
---|---|
description | Returns the specified check. |
example url | http://hostname:8080/api/core/v2/namespaces/default/checks/check-cpu |
response type | Map |
response codes |
|
output |
|
Create or update a check
The /checks/:check
API endpoint provides HTTP PUT access to create and update :check
definitions, specified by check name.
Example
In the following example, an HTTP PUT request is submitted to the /checks/:check
API endpoint to update the check-cpu
check, resulting in an HTTP 200 OK
response and the updated check definition.
curl -X PUT \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"command": "check-cpu.sh -w 75 -c 90",
"handlers": [
"slack"
],
"interval": 60,
"publish": true,
"subscriptions": [
"linux"
],
"metadata": {
"name": "check-cpu",
"namespace": "default"
}
}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/checks/check-cpu
HTTP/1.1 201 Created
API Specification
/checks/:check (PUT) | |
---|---|
description | Creates or updates the specified Sensu check. |
example URL | http://hostname:8080/api/core/v2/namespaces/default/checks/check-cpu |
payload |
|
payload parameters | Required check attributes: interval (integer) or cron (string) and a metadata scope that contains name (string) and namespace (string). For more information about creating checks, see the check reference. |
response codes |
|
Update a check with PATCH
The /checks/:check
API endpoint provides HTTP PATCH access to update :check
definitions, specified by check name.
NOTE: You cannot change a resource’s name
or namespace
with a PATCH request.
Use a PUT request instead.
Also, you cannot add elements to an array with a PATCH request — you must replace the entire array.
Example
In the following example, an HTTP PATCH request is submitted to the /checks/:check
API endpoint to update the subscriptions array for the check-cpu
check, resulting in an HTTP 200 OK
response and the updated check definition.
We support JSON merge patches, so you must set the Content-Type
header to application/merge-patch+json
for PATCH requests.
curl -X PATCH \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/merge-patch+json' \
-d '{
"subscriptions": [
"linux",
"health"
]
}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/checks/check-cpu
HTTP/1.1 200 OK
API Specification
/checks/:check (PATCH) | |
---|---|
description | Updates the specified Sensu check. |
example URL | http://hostname:8080/api/core/v2/namespaces/default/checks/check-cpu |
payload |
|
response codes |
|
Delete a check
The /checks/:check
API endpoint provides HTTP DELETE access to delete a check from Sensu, specified by the check name.
Example
The following example shows a request to the /checks/:check
API endpoint to delete the check named check-cpu
, resulting in a successful HTTP 204 No Content
response.
curl -X DELETE \
-H "Authorization: Key $SENSU_API_KEY" \
http://127.0.0.1:8080/api/core/v2/namespaces/default/checks/check-cpu
HTTP/1.1 204 No Content
API Specification
/checks/:check (DELETE) | |
---|---|
description | Removes the specified check from Sensu. |
example url | http://hostname:8080/api/core/v2/namespaces/default/checks/check-cpu |
response codes |
|
Create an ad hoc check execution request
The /checks/:check/execute
API endpoint provides HTTP POST access to create an ad hoc check execution request so you can execute a check on demand.
Example
In the following example, an HTTP POST request is submitted to the /checks/:check/execute
API endpoint to execute the check-cpu
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: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"check": "check-cpu",
"subscriptions": [
"entity:i-424242"
]
}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/checks/check-cpu/execute
HTTP/1.1 202 Accepted
{"issued":1543861798}
PRO TIP: Include the subscriptions
attribute with the request body to override the subscriptions configured in the check definition.
This gives you the flexibility to execute a check on any Sensu entity or group of entities on demand.
API Specification
/checks/:check/execute (POST) | |
---|---|
description | Creates an ad hoc request to execute the specified check. |
example URL | http://hostname:8080/api/core/v2/namespaces/default/checks/check-cpu/execute |
payload |
|
payload parameters |
|
response codes |
|
Assign a hook to a check
The /checks/:check/hooks/:type
API endpoint provides HTTP PUT access to assign a hook to a check.
Example
In the following example, an HTTP PUT request is submitted to the /checks/:check/hooks/:type
API endpoint, assigning the process_tree
hook to the check-cpu
check in the event of a critical
type check result, resulting in a successful HTTP 204 No Content
response.
curl -X PUT \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"critical": [
"process_tree"
]
}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/checks/check-cpu/hooks/critical
HTTP/1.1 201 Created
API Specification
checks/:check/hooks/:type (PUT) | |
---|---|
description | Assigns a hook to a check (specified by the check name and check response type). |
example URL | http://hostname:8080/api/core/v2/namespaces/default/checks/check-cpu/hooks/critical |
example payload |
|
payload parameters | This endpoint requires a JSON map of check response types (for example, critical or warning ). Each must contain an array of hook names. |
response codes |
|
Remove a hook from a check
The /checks/:check/hooks/:type/hook/:hook
API endpoint provides HTTP DELETE access to a remove a hook from a check.
Example
The following example shows a request to the /checks/:check/hooks/:type/hook/:hook
API endpoint 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: Key $SENSU_API_KEY" \
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 (specified by the check name, check response type, and hook name). See the checks reference for available types. |
example url | http://hostname:8080/api/core/v2/namespaces/default/checks/check-cpu/hooks/critical/hook/process_tree |
response codes |
|