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
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output 
[
  {
    "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"
    }
  }
]

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
  • Success: 200 (OK)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)
output 
{
  "type": "Search",
  "api_version": "searches/v1",
  "metadata": {
    "name": "silenced-events",
    "namespace": "default"
  },
  "spec": {
    "parameters": [
      "silenced:true"
    ],
    "resource": "core.v2/Event"
  }
}

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 
{
  "type": "Search",
  "api_version": "searches/v1",
  "metadata": {
    "name": "silenced-events",
    "namespace": "default"
  },
  "spec": {
    "parameters": [
      "silenced:true"
    ],
    "resource": "core.v2/Event"
  }
}
response codes
  • Success: 201 (Created)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

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
  • Success: 204 (No Content)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)