API overview

Sensu Go 5.9 includes API v2.

The Sensu backend REST API provides access to Sensu workflow configurations and monitoring event data. For the Sensu agent API, see the agent reference.

URL format

Sensu API endpoints use the standard URL format /api/{group}/{version}/namespaces/{namespace} where:

  • {group} is the API group. All currently existing Sensu API endpoints are of group core.
  • {version} is the API version. Sensu Go 5.9 uses API v2.
  • {namespace} is the namespace name. The examples in these API docs use the default namespace. The Sensu API requires that the authenticated user have the correct access permissions for the namespace specified in the URL. If the authenticated user has the correct cluster-wide permissions, you can leave out the /namespaces/{namespace} portion of the URL to access Sensu resources across namespaces. See the RBAC reference for more information about configuring Sensu users and access controls.

Data format

The API uses JSON formatted requests and responses. In terms of sensuctl output types, the Sensu API uses the json format, not wrapped-json.


The Sensu Go API is versioned according to the format v{majorVersion}{stabilityLevel}{iterationNumber}, in which v2 is stable version 2. The Sensu API guarantees backward compatibility for stable versions of the API.

Sensu makes no guarantee that an alpha or beta API will be maintained for any period of time. Alpha versions should be considered under active development and may not be published for every release. Beta APIs, while more stable than alpha versions, offer similarly short-lived lifespans and also provide no guarantee of programmatic conversions when the API is updated.

Access control

With the exception of the health and metrics APIs, the Sensu API requires authentication using a JWT access token. You can generate access tokens and refresh tokens using the authentication API and your Sensu username and password.

Basic authentication using the authentication API

The /auth API endpoint lets you generate short-lived API tokens using your Sensu username and password.

  1. Retrieve an access token for your user. For example, to generate an access token using the default admin credentials:

    curl -u 'admin:P@ssw0rd!' http://localhost:8080/auth
    The access token should be included in the output, along with a refresh token:
      "access_token": "eyJhbGciOiJIUzI1NiIs...",
      "expires_at": 1544582187,
      "refresh_token": "eyJhbGciOiJIUzI1NiIs..."

  2. Copy the access token into the authentication header of the API request. For example:

    curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \

  3. Access tokens last for around 15 minutes. When your token expires, you should see a 401 Unauthorized response from the API. To generate a new access token, use the /auth/token API endpoint, including the expired access token in the authorization header and the refresh token in the request body:

    curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
    -H 'Content-Type: application/json' \
    -d '{"refresh_token": "eyJhbGciOiJIUzI1NiIs..."}' \
    The new access token should be included in the output:
      "access_token": "eyJhbGciOiJIUzI1NiIs...",
      "expires_at": 1561055277,
      "refresh_token": "eyJhbGciOiJIUzI1NiIs..."

Generating an API token using sensuctl

You can also generate an API access token using the sensuctl command-line tool. The user credentials that you use to log in to sensuctl determine your permissions to get, list, create, update, and delete resources using the Sensu API.

  1. Install and log in to sensuctl.

  2. Retrieve an access token for your user:

    cat ~/.config/sensu/sensuctl/cluster|grep access_token
    The access token should be included in the output:
    "access_token": "eyJhbGciOiJIUzI1NiIs...",

  3. Copy the access token into the authentication header of the API request. For example:

    curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \

  4. Access tokens last for around 15 minutes. If your token expires, you should see a 401 Unauthorized response from the API. To regenerate a valid access token, first run any sensuctl command (like sensuctl event list) then repeat step 2.


LICENSED TIER: Unlock API filtering in Sensu Go with a Sensu license. To activate your license, see the getting started guide.

The Sensu API supports filtering for all GET endpoints that return an array. You can filter resources based on their labels with a label selector using the labelSelector query parameter and on certain pre-determined fields with a field selector using the fieldSelector query parameter.

For example, the following request filters the response to only include resources that have a label entry region with the value us-west-1. We will use the flag --data-urlencode in curl so it encodes the query parameter for us, in conjunction with the -G flag so it appends the data to the URL.

curl -H "Authorization: Bearer $SENSU_TOKEN" -G \
--data-urlencode 'labelSelector=region == "us-west-1"'

Label selector

A label selector can use any label attributes to group a set of resources. All resources support labels within the metadata object. For example, see entities metadata attributes.

Field selector

A field selector can use certain fields of resources to organize and select subsets of resources. Here’s the list of available fields.

Resource Fields
Asset asset.name asset.namespace asset.filters
Check check.name check.namespace check.handlers check.publish check.round_robin check.runtime_assets check.subscriptions
ClusterRole clusterrole.name
ClusterRoleBinding clusterrolebinding.name clusterrolebinding.role_ref.name clusterrolebinding.role_ref.type
Entity entity.name entity.namespace entity.deregister entity.entity_class entity.subscriptions
Event event.name event.namespace event.check.handlers event.check.publish event.check.round_robin event.check.runtime_assets event.check.status event.check.subscriptions event.entity.deregister event.entity.entity_class event.entity.subscriptions
Extension extension.name extension.namespace
Filter filter.name filter.namespace filter.action filter.runtime_assets
Handler handler.name handler.namespace handler.filters handler.handlers handler.mutator handler.type
Hook hook.name hook.namespace
Mutator mutator.name mutator.namespace mutator.runtime_assets
Namespace namespace.name
Role role.name role.namespace
RoleBinding rolebinding.name rolebinding.namespace rolebinding.role_ref.name rolebinding.role_ref.type
Silenced silenced.name silenced.namespace silenced.check silenced.creator silenced.expire_on_resolve silenced.subscription
User user.username user.disabled user.groups

Supported operators

There are two equality-based operators supported, == (equality) and != (inequality). For example, the following statements are possible:

check.publish == true
check.namespace != "default"

Additionally, there are two set-based operators to deal with lists of values, in and notin. For example, the following statements are possible:

linux in check.subscriptions
slack notin check.handlers
check.namespace in [dev,production]

Combining selectors and statements

A field or label selector can be made of multiple statements which are separated with the logical operator && (AND). For example, the following curl request looks up checks that are configured to be published and have the slack handler:

curl -H "Authorization: Bearer $SENSU_TOKEN" -G \
--data-urlencode 'fieldSelector=check.publish == true && slack in check.handlers'

In addition to selectors with multiple statements, both field and label selectors can be used at the same time:

curl -H "Authorization: Bearer $SENSU_TOKEN" -G \
--data-urlencode 'fieldSelector=slack in check.handlers' \
--data-urlencode 'labelSelector=region != "us-west-1"'

Request size

API request bodies are limited to 0.512 MB in size.