Searches API
COMMERCIAL FEATURE: Access the searches API in the packaged Sensu Go distribution. For more information, see Get started with commercial features.
NOTE: Requests to the searches 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 searches
The /searches
API endpoint provides HTTP GET access to the list of saved searches.
Example
The following example demonstrates a request to the /search
API endpoint, resulting in a JSON array that contains saved search definitions.
curl -X GET \
http://127.0.0.1:8080/api/enterprise/searches/v1/namespaces/default/searches \
-H "Authorization: Key $SENSU_API_KEY"
HTTP/1.1 200 OK
[
{
"type": "Search",
"api_version": "searches/v1",
"metadata": {
"name": "incidents-us-west",
"namespace": "default"
},
"spec": {
"parameters": [
"labelSelector:region == \"us-west-1\"",
"status:incident"
],
"resource": "core.v2/Event"
}
},
{
"type": "Search",
"api_version": "searches/v1",
"metadata": {
"name": "silenced-events",
"namespace": "default"
},
"spec": {
"parameters": [
"silenced:true"
],
"resource": "core.v2/Event"
}
},
{
"type": "Search",
"api_version": "searches/v1",
"metadata": {
"name": "web-agent",
"namespace": "default"
},
"spec": {
"parameters": [
"class:agent",
"subscription:web"
],
"resource": "core.v2/Entity"
}
}
]
API Specification
/searches (GET) | |
---|---|
description | Returns the list of saved searches. |
example url | http://hostname:8080/api/enterprise/searches/v1/namespaces/default/searches |
response filtering | This endpoint supports API response filtering. |
response type | Array |
response codes |
|
output |
|
Get a specific search
The /searches/:search
API endpoint provides HTTP GET access to a specific :search
definition, by the saved search name
.
Example
In the following example, querying the /searches/:search
API endpoint returns a JSON map that contains the requested :search
definition (in this example, for the :search
named silenced-events
).
curl -X GET \
http://127.0.0.1:8080/api/enterprise/searches/v1/namespaces/default/searches/silenced-events \
-H "Authorization: Key $SENSU_API_KEY"
HTTP/1.1 200 OK
{
"type": "Search",
"api_version": "searches/v1",
"metadata": {
"name": "silenced-events",
"namespace": "default"
},
"spec": {
"parameters": [
"silenced:true"
],
"resource": "core.v2/Event"
}
}
API Specification
/searches/:search (GET) | |
---|---|
description | Returns the specified search. |
example url | http://hostname:8080/api/enterprise/searches/v1/namespaces/default/searches/silenced-events |
response type | Map |
response codes |
|
output |
|
Create or update a search
The /searches/:search
API endpoint provides HTTP PUT access to create or update a saved search by the saved search name
.
Example
In the following example, an HTTP PUT request is submitted to the /searches/:search
API endpoint to create or update a saved search for events that are silenced.
The request includes the saved search definition in the request body and returns a successful HTTP 200 OK
response and the created or updated saved search definition.
curl -X PUT \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"type": "Search",
"api_version": "searches/v1",
"metadata": {
"name": "silenced-events",
"namespace": "default"
},
"spec": {
"parameters": [
"silenced:true"
],
"resource": "core.v2/Event"
}
}' \
http://127.0.0.1:8080/api/enterprise/searches/v1/namespaces/default/searches/silenced-events
HTTP/1.1 200 OK
API Specification
/searches/:search (PUT) | |
---|---|
description | Creates or updates the specified saved search. |
example URL | http://hostname:8080/api/enterprise/searches/v1/namespaces/default/searches/silenced-events |
payload |
|
response codes |
|
Delete a search
The /searches/:search
API endpoint provides HTTP DELETE access to delete a saved search from Sensu (specified by the saved search name).
Example
The following example shows a request to the /searches/:search
API endpoint to delete the saved search silenced-events
, 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/enterprise/searches/v1/namespaces/default/searches/silenced-events
HTTP/1.1 204 No Content
API Specification
/searches/:search (DELETE) | |
---|---|
description | Removes a saved search from Sensu (specified by the search name). |
example url | http://hostname:8080/api/enterprise/searches/v1/namespaces/default/searches/silenced-events |
response codes |
|