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
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output 
[
  {
    "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"
    }
  }
]

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 
{
  "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: 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
  • Success: 201 (Created)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

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
  • Success: 200 (OK)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)
output 
{
  "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"
  }
}

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 
{
  "command": "check-cpu.sh -w 75 -c 90",
  "handlers": [
    "slack"
  ],
  "interval": 60,
  "publish": true,
  "subscriptions": [
    "linux"
  ],
  "metadata": {
    "name": "check-cpu",
    "namespace": "default"
  }
}
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
  • Success: 201 (Created)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

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 
{
  "subscriptions": [
    "linux",
    "health"
  ]
}
response codes
  • Success: 200 (OK)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

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
  • Success: 204 (No Content)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)

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 
{
  "check": "check-cpu",
  "subscriptions": [
    "entity:i-424242"
  ]
}
payload parameters
  • Required: check (the name of the check to execute).
  • Optional: subscriptions (an array of subscriptions to publish the check request to). When provided with the request, the subscriptions attribute overrides any subscriptions configured in the check definition.
response codes
  • Success: 202 (Accepted)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

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 
{
  "critical": [
    "process_tree"
  ]
}
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
  • Success: 201 (Created)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

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
  • Success: 204 (No Content)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)