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)

Checks API

Get all checks

Example

API Specification

Create a new check

Example

API Specification

Get a specific check

Example

API Specification

Create or update a check

Example

API Specification

Update a check with PATCH

Example

API Specification

Delete a check

Example

API Specification

Create an ad hoc check execution request

Example

API Specification

Assign a hook to a check

Example

API Specification

Remove a hook from a check

Example

API Specification

Register your Sensu installation — Get rewards!

About Sensu

Navigation

Resources

Community

Get In Touch

Join Our Community