Clients API
- The
/clientsAPI endpoint - The
/clients/:clientAPI endpoints - The
/clients/:client/historyAPI endpoint
The /clients API Endpoint
The /clients API endpoint provides HTTP GET and POST access to the Sensu
client registry.
/clients (GET)
The /clients endpoint provides HTTP GET access to client registry data as
published via client keepalives, generated for a proxy client, or
created via HTTP POST to the /clients API.
EXAMPLES
The following example demonstrates a /clients API query which returns a JSON
Array of JSON Hashes containing client data.
$ curl -s http://127.0.0.1:3000/clients | jq .
[
{
"_id": "us_west1/i-424242",
"address": "127.0.0.1",
"dc": "us_west1",
"name": "i-424242",
"silenced": false,
"status": 0,
"subscriptions": [
"dev"
],
"socket": {
"port": 3030,
"bind": "127.0.0.1"
},
"environment": "development",
"timestamp": 1458625739,
"version": "1.5.0"
}
]API Specification
| /clients (GET) | |
|---|---|
| description | Returns a list of clients by name and datacenter (dc). Since clients use the Sensu Core package, the version returned by this endpoint reflects the current version of Sensu Core instead of Sensu Enterprise. |
| example url | http://hostname:3000/clients |
| response type | Array |
| response codes |
|
| output | |
The /clients/:client API Endpoints
The /clients/:client API endpoint provides read and delete access to specific
Sensu client data in the Sensu client registry, by client name.
/clients/:client (GET)
The /clients/:client endpoint provides HTTP GET access to specific client
definitions in the client registry as published via client keepalives,
generated for a proxy client, or created via POST to the /clients
API.
EXAMPLE
In the following example, querying the /clients/:client API returns a JSON
Hash containing the requested client data for the client named
i-424242.
$ curl -s http://127.0.0.1:3000/clients/i-424242 | jq .
{
"_id": "us_west1/i-424242",
"address": "127.0.0.1",
"dc": "us_west1",
"name": "i-424242",
"environment": "development",
"silenced": false,
"subscriptions": [
"dev"
],
"socket": {
"port": 3030,
"bind": "127.0.0.1"
},
"timestamp": 1458625739,
"version": "1.5.0"
}The following example demonstrates a request for client data for a non-existent
client named non-existent-client, which results in a 404 (Not Found) HTTP
response code.
$ curl -s -i http://127.0.0.1:3000/clients/non-existent-client
HTTP/1.1 404 Not Found
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
Content-Length: 0
Connection: keep-alive
Server: thinAPI Specification
| /clients/:client (GET) | |
|---|---|
| description | Returns a client with the name and datacenter (dc) |
| example url | http://hostname:3000/clients/i-424242 |
| parameters |
|
| response type | Hash |
| response codes |
|
| output | |
/clients/:client (DELETE)
The /clients/:client endpoint provides HTTP DELETE access to specific client
definitions in the client registry.
EXAMPLE
The following example demonstrates a request to delete a client named
api-example, resulting in a 202 (Accepted) HTTP response code.
$ curl -s -i -X DELETE http://127.0.0.1:3000/clients/api-example
HTTP/1.1 202 Accepted
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
Content-Length: 21
Connection: keep-alive
Server: thinThe following example demonstrates a request to delete a non-existent :client
named non-existent-client, resulting in a 404 (Not Found) HTTP response
code (i.e. HTTP/1.1 404 Not Found).
$ curl -s -i -X DELETE http://127.0.0.1:3000/clients/non-existent-client
HTTP/1.1 404 Not Found
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
Content-Length: 0
Connection: keep-alive
Server: thinAPI Specification
| /clients/:client (DELETE) | |
|---|---|
| description | Removes a client, resolving its current events. (delayed action) |
| example url | http://hostname:3000/clients/i-424242 |
| parameters |
|
| response codes |
|
The /clients/:client/history API Endpoint
The /clients/:client/history API endpoint provides HTTP GET access to check result data
for a specified client.
/clients/:client/history (GET)
EXAMPLE
In the following example, querying the /clients/:client/history API returns a JSON
Array of JSON Hashes containing check result data for a client named i-424242.
$ curl -s http://127.0.0.1:3000/clients/i-424242/history | jq .
[
{
"check": "check_disk_usage",
"client": "i-424242",
"dc": "us_east1",
"history": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
"last_execution": 1539364800,
"last_result": {
"command": "/opt/sensu/embedded/bin/metrics-disk-usage.rb",
"duration": 0.059,
"executed": 1539364800,
"handlers": ["influxdb"],
"interval": 10,
"issued": 1539364800,
"name": "check_disk_usage",
"output": "sensu.disk_usage.root.used 2328 1539364800\n...",
"status": 0,
"subscribers": ["cpu-metrics"],
"type": "metric"
},
"last_status": 0,
"silenced": false,
"silenced_by": null
},
{
"check": "check_curl_timings",
"client": "i-424242",
"dc": "us_east1",
"history": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
"last_execution": 1539364794,
"last_result": {
"command": "/opt/sensu/embedded/bin/metrics-curl.rb localhost",
"duration": 0.069,
"executed": 1539364794,
"handlers": ["influxdb"],
"interval": 10,
"issued": 1539364794,
"name": "check_curl_timings",
"output": "sensu.curl_timings.time_total 0.000 1539364794\n...",
"status": 0,
"subscribers": ["http-metrics"],
"type": "metric"
},
"last_status": 0,
"silenced": false,
"silenced_by": null
}
]API Specification
| /clients/:client/history (GET) | |
|---|---|
| description | Returns an array of check results by check name and datacenter (dc) |
| example url | http://hostname:3000/clients/i-424242/history |
| parameters |
|
| response type | Array |
| response codes |
|
| output | |