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 $SENSU_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
pagination This endpoint supports pagination using the limit and continue query parameters. See the API overview for details.
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 $SENSU_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: interval (integer) or cron (string), 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 $SENSU_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)

EXAMPLE

In the following example, an HTTP PUT request is submitted to the /checks/:check API to update the check-cpu check, resulting in a 200 (OK) HTTP response code and the updated check definition.

curl -X PUT \
-H "Authorization: Bearer $SENSU_TOKEN" \
-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 200 OK

API Specification

/checks/:check (PUT)
description Create or update a Sensu check given the name of the check as a URL parameter.
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 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)

/checks/:check (DELETE)

The /checks/:check API endpoint provides HTTP DELETE access to delete a check from Sensu given the check name.

EXAMPLE

The following example shows a request to delete the check named check-cpu, resulting in a successful HTTP 204 No Content response.

curl -X DELETE \
-H "Authorization: Bearer $SENSU_TOKEN" \
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 a check from Sensu given the check name.
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)

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 $SENSU_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}

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 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",
  "subscriptions": [
    "entity:i-424242"
  ]
}
payload parameters check (required): the name of the check to execute, and subscriptions (optional): 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: 200 (OK)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

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

/checks/:check/hooks/:type (PUT)

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, assigning the process_tree hook to the check-cpu check in the event of a critical type check result, resulting in a successful 204 (No Content) HTTP response code.

curl -X PUT \
-H "Authorization: Bearer $SENSU_TOKEN" \
-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 204 No Content

API Specification

checks/:check/hooks/:type (PUT)
description Assigns a hook to a check given 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": [
    "example-hook1",
    "example-hook2"
  ]
}
payload parameters This endpoint requires a JSON map of check response types (for example: critical, warning), each containing an array of hook names.
response codes
  • Success: 204 (No Content)
  • 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 remove a hook from a check.

EXAMPLE

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

curl -X DELETE \
-H "Authorization: Bearer $SENSU_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, 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)