Sensu Clients API

Reference documentation


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 (i.e. the Sensu client registry).

$ curl -s http://127.0.0.1:4567/clients | jq .
[
  {
    "timestamp": 1458625739,
    "version": "1.2.0",
    "socket": {
      "port": 3030,
      "bind": "127.0.0.1"
    },
    "subscriptions": [
      "dev"
    ],
    "environment": "development",
    "address": "127.0.0.1",
    "name": "client-01"
  }
]

NOTE: for larger Sensu installations it may be undesirable to get the entire client registry in a single API request. The /clients API provides pagination controls via the limit and offset url parameters (see below).

API Specification

/clients (GET)
desc.
Returns a list of clients.
example url
http://hostname:4567/clients
parameters
  • limit
    • required: false
    • type: Integer
    • description: The number of clients to return.
    • example: http://hostname:4567/clients?limit=100
  • offset
    • required: false
    • type: Integer
    • depends: limit
    • description: The number of clients to offset before returning items.
    • example: http://hostname:4567/clients?limit=100&offset=100
response type
Array
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output
[
    {
        "name": "i-334455",
        "address": "192.168.0.2",
        "subscriptions": [
            "chef-client",
            "sensu-server"
        ],
        "timestamp": 1324674972
    },
    {
        "name": "i-424242",
        "address": "192.168.0.3",
        "subscriptions": [
            "chef-client",
            "webserver",
            "memcached"
        ],
        "timestamp": 1324674956
    }
]

/clients (POST)

The /clients endpoint provides HTTP POST access to the client registry.

EXAMPLES

The following example demonstrates submitting an HTTP POST to the /clients API, resulting in a 201 (Created) HTTP response code (i.e. HTTP/1.1 201 Created) and a JSON Hash containing the client name.

$ curl -s -i \
-X POST \
-H 'Content-Type: application/json' \
-d '{"name": "api-example","address": "10.0.2.100","subscriptions":["default"],"environment":"production"}' \
http://127.0.0.1:4567/clients

HTTP/1.1 201 Created
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: 22
Connection: keep-alive
Server: thin

{"name":"api-example"}

API Specification

/clients (POST)
desc
Create or update client data (e.g. Sensu proxy clients).
example URL
http://hostname:4567/clients
payload
{
    "name": "gateway-router",
    "address": "192.168.0.1",
    "subscriptions": [
        "network",
        "snmp"
    ],
    "environment": "production"
}
response codes
  • Success: 201 (Created)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

The /clients/:client API Endpoint(s)

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 (i.e. for the client named client-01).

$ curl -s http://127.0.0.1:4567/clients/client-01 | jq .
{
  "timestamp": 1458625739,
  "version": "1.2.0",
  "socket": {
    "port": 3030,
    "bind": "127.0.0.1"
  },
  "subscriptions": [
    "dev"
  ],
  "environment": "development",
  "address": "127.0.0.1",
  "name": "client-01"
}

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 (i.e. HTTP/1.1 404 Not Found).

$ curl -s -i http://127.0.0.1:4567/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: thin

API Specification

/clients/:client (GET)
desc.
Returns a client.
example url
http://hostname:4567/clients/i-424242
response type
Hash
response codes
  • Success: 200 (OK)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)
output
{
    "name": "i-424242",
    "address": "192.168.0.3",
    "subscriptions": [
        "chef-client",
        "webserver",
        "memcached"
    ],
   "timestamp": 1324674956
}

/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 (i.e. HTTP/1.1 202 Accepted) and a JSON Hash containing an issued timestamp.

$ curl -s -i -X DELETE http://127.0.0.1:4567/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: thin

{"issued":1460136855}

The 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:4567/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: thin

API Specification

/clients/:client (DELETE)
desc.
Removes a client, resolving its current events. (delayed action)
example url
http://hostname:4567/clients/i-424242
parameters
  • invalidate
    • required: false
    • type: Boolean
    • description: If the Sensu client should be invalidated, disallowing further client keepalives and check results until the client is successfully removed from the client registry.
    • example: http://hostname:4567/clients/i-424242?invalidate=true
  • invalidate_expire
    • required: false
    • type: Integer
    • description: If the Sensu client should be invalidated for a specified amount of time (in seconds), disallowing further client keepalives and check results even after the client is successfully removed from the client registry.
    • example: http://hostname:4567/clients/i-424242?invalidate=true&invalidate_expire=3600
response codes
  • Success: 202 (Accepted)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)

The /clients/:client/history API Endpoint(s)

The /clients/:client/history API is being deprecated in favor of the Sensu Results API. This API predates the /results APIs and provides less functionality than the newer alternative.

Start your FREE trial today.

Already using Sensu Core? Upgrade to Sensu Enterprise today to take advantage of its enterprise console, added-value features, built-in integrations, FREE annual training, and enterprise-class support.