Entities API
NOTE: Requests to the entities 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 entities
The /entities API endpoint provides HTTP GET access to entity data.
Example
The following example demonstrates a request to the /entities API endpoint, resulting in a JSON array that contains the entity definitions.
curl -X GET \
http://127.0.0.1:8080/api/core/v2/namespaces/default/entities \
-H "Authorization: Key $SENSU_API_KEY"
HTTP/1.1 200 OK
[
{
"entity_class": "agent",
"sensu_agent_version": "1.0.0",
"system": {
"hostname": "sensu-centos",
"os": "linux",
"platform": "centos",
"platform_family": "rhel",
"platform_version": "7.4.1708",
"network": {
"interfaces": [
{
"name": "lo",
"addresses": [
"127.0.0.1/8",
"::1/128"
]
},
{
"name": "enp0s3",
"mac": "08:00:27:11:ad:d2",
"addresses": [
"10.0.2.15/24",
"fe80::f50c:b029:30a5:3e26/64"
]
},
{
"name": "enp0s8",
"mac": "08:00:27:9f:5d:f3",
"addresses": [
"172.28.128.3/24",
"fe80::a00:27ff:fe9f:5df3/64"
]
}
]
},
"arch": "amd64",
"libc_type": "glibc",
"vm_system": "kvm",
"vm_role": "host",
"cloud_provider": "",
"processes": [
{
"name": "Slack",
"pid": 1349,
"ppid": 0,
"status": "Ss",
"background": true,
"running": true,
"created": 1582137786,
"memory_percent": 1.09932518,
"cpu_percent": 0.3263987595984941
},
{
"name": "Slack Helper",
"pid": 1360,
"ppid": 1349,
"status": "Ss",
"background": true,
"running": true,
"created": 1582137786,
"memory_percent": 0.146866455,
"cpu_percent": 0.308976181461092553
}
]
},
"subscriptions": [
"entity:sensu-centos"
],
"last_seen": 1543349936,
"deregister": false,
"deregistration": {},
"user": "agent",
"redact": [
"password",
"passwd",
"pass",
"api_key",
"api_token",
"access_key",
"secret_key",
"private_key",
"secret"
],
"metadata": {
"name": "sensu-centos",
"namespace": "default",
"created_by": "admin",
"labels": null,
"annotations": null
}
}
]API Specification
| /entities (GET) | |
|---|---|
| description | Returns the list of entities. |
| example url | http://hostname:8080/api/core/v2/namespaces/default/entities |
| 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 |
|
| output | |
Create a new entity
The /entities API endpoint provides HTTP POST access to create a Sensu entity.
Example
In the following example, an HTTP POST request is submitted to the /entities API endpoint to create a proxy entity named sensu-centos.
The request includes the entity definition in the request body and returns a successful HTTP 200 OK response.
curl -X POST \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"entity_class": "proxy",
"sensu_agent_version": "1.0.0",
"subscriptions": [
"web"
],
"deregister": false,
"deregistration": {},
"metadata": {
"name": "sensu-centos",
"namespace": "default",
"labels": null,
"annotations": null
}
}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/entities
HTTP/1.1 200 OKAPI Specification
| /entities (POST) | |
|---|---|
| description | Creates a Sensu entity. |
| example URL | http://hostname:8080/api/core/v2/namespaces/default/entities |
| payload | |
| response codes |
|
Get a specific entity
The /entities/:entity API endpoint provides HTTP GET access to entity data for specific :entity definitions, by entity name.
Example
In the following example, querying the /entities/:entity API endpoint returns a JSON map that contains the requested :entity definition (in this example, for the :entity named sensu-centos).
curl -X GET \
http://127.0.0.1:8080/api/core/v2/namespaces/default/entities/sensu-centos \
-H "Authorization: Key $SENSU_API_KEY"
HTTP/1.1 200 OK
{
"entity_class": "agent",
"sensu_agent_version": "1.0.0",
"system": {
"hostname": "sensu-centos",
"os": "linux",
"platform": "centos",
"platform_family": "rhel",
"platform_version": "7.4.1708",
"network": {
"interfaces": [
{
"name": "lo",
"addresses": [
"127.0.0.1/8",
"::1/128"
]
},
{
"name": "enp0s3",
"mac": "08:00:27:11:ad:d2",
"addresses": [
"10.0.2.15/24",
"fe80::f50c:b029:30a5:3e26/64"
]
},
{
"name": "enp0s8",
"mac": "08:00:27:9f:5d:f3",
"addresses": [
"172.28.128.3/24",
"fe80::a00:27ff:fe9f:5df3/64"
]
}
]
},
"arch": "amd64",
"libc_type": "glibc",
"vm_system": "kvm",
"vm_role": "host",
"cloud_provider": "",
"processes": [
{
"name": "Slack",
"pid": 1349,
"ppid": 0,
"status": "Ss",
"background": true,
"running": true,
"created": 1582137786,
"memory_percent": 1.09932518,
"cpu_percent": 0.3263987595984941
},
{
"name": "Slack Helper",
"pid": 1360,
"ppid": 1349,
"status": "Ss",
"background": true,
"running": true,
"created": 1582137786,
"memory_percent": 0.146866455,
"cpu_percent": 0.308976181461092553
}
]
},
"subscriptions": [
"entity:sensu-centos"
],
"last_seen": 1543349936,
"deregister": false,
"deregistration": {},
"user": "agent",
"redact": [
"password",
"passwd",
"pass",
"api_key",
"api_token",
"access_key",
"secret_key",
"private_key",
"secret"
],
"metadata": {
"name": "sensu-centos",
"namespace": "default",
"created_by": "admin",
"labels": null,
"annotations": null
}
}API Specification
| /entities/:entity (GET) | |
|---|---|
| description | Returns the specified entity. |
| example url | http://hostname:8080/api/core/v2/namespaces/default/entities/sensu-centos |
| response type | Map |
| response codes |
|
| output | |
Create or update an entity
The /entities/:entity API endpoint provides HTTP PUT access to create or update the specified Sensu entity.
Example
In the following example, an HTTP PUT request is submitted to the /entities/:entity API endpoint to update the entity named sensu-centos.
The request includes the updated entity definition in the request body and returns a successful HTTP 200 OK response.
curl -X PUT \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"entity_class": "proxy",
"sensu_agent_version": "1.0.0",
"subscriptions": [
"web",
"system"
],
"deregister": false,
"deregistration": {},
"metadata": {
"name": "sensu-centos",
"namespace": "default",
"labels": null,
"annotations": null
}
}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/entities/sensu-centos
HTTP/1.1 200 OKAPI Specification
| /entities/:entity (PUT) | |
|---|---|
| description | Creates or updates the specified Sensu entity.
NOTE: When you create an entity via an HTTP PUT request, the entity will use the namespace in the request URL. |
| example URL | http://hostname:8080/api/core/v2/namespaces/default/entities/sensu-centos |
| payload | |
| response codes |
|
Delete an entity
The /entities/:entity API endpoint provides HTTP DELETE access to delete an entity from Sensu (specified by the entity name).
Example
The following example shows a request to the /entities/:entity API endpoint to delete the entity server1, resulting in a successful HTTP 204 No Content response.
curl -X DELETE \
http://127.0.0.1:8080/api/core/v2/namespaces/default/entities/server1 \
-H "Authorization: Key $SENSU_API_KEY"
HTTP/1.1 204 No ContentAPI Specification
| /entities/:entity (DELETE) | |
|---|---|
| description | Removes a entity from Sensu (specified by the entity name). |
| example url | http://hostname:8080/api/core/v2/namespaces/default/entities/server1 |
| response codes |
|
