SearchStax Cloud API – Alerts

Overview

SearchStax provides an API supporting the creation, deletion and management of SearchStax Cloud deployments.

Platinum and Platinum Plus Clients Only!

The SearchStax API suite is available to our Platinum and Platinum Plus clients only, as noted on our Pricing page.

This page describes how to set up and manage alerts through API methods.

The API can be accessed through any tool that assembles HTTP requests and dispatch them to a server. Among these would be the Python coreapi package, the Postman tool, and cURL. For Windows, use PowerShell 7+.

Account Owner, Admin, or Technical Contact

To run the SearchStax Provisioning API, you must be the account Owner, an account Admin, or a Technical Contact. See SearchStax User Roles.

Symbols enclosed in carets (< and >) such as <username> are metavariables. Substitute your local values when you encounter them in the examples.

Contents:

Related Pages:

Alerts

The Provisioning API provides methods for remotely managing alerts and incidents.

account > alerts > metrics

This method generates a list of the metrics that are available for setting alerts.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/alerts/metrics/

where <account_name> is the name of the tenant account.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/alerts/metrics/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"

$RESULTS = Invoke-RestMethod -Method Get -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/alerts/metrics/" 
$RESULTS = $RESULTS | ConvertTo-Json | Out-File C:\metrics.txt

The response is a list of JSON objects describing individual metrics.

[
    {
        "name":  "system_cpu_usage",
        "unit":  [
                     "percentage"
                 ],
        "description":  "Metrics for CPU usage in percentage."
    },
    {
        "name":  "system_disk_space_used",
        "unit":  [
                     "KB",
                     "MB",
                     "GB"
                 ],
        "description":  "Used disk space on this device."
    },
    {
        "name":  "system_disk_space_free",
        "unit":  [
                     "KB",
                     "MB",
                     "GB"
                 ],
        "description":  "Free Disk space left on the device."
    },
    {
        "name":  "search_timeouts",
        "unit":  [
                     "number"
                 ],
        "description":  "Timeouts reported while performing a search in Solr."
    }
]

account > deployment > incidents

This method lists the incidents for a deployment. (Incidents are created by alerts.)

GET https://app.searchstax.com/api/rest/v2/account/{account_name}/deployment/{uid}/incidents/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/incidents/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$RESULTS = Invoke-RestMethod -Method Get -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/incidents/" 
$RESULTS = $RESULTS | ConvertTo-Json

The response is a JSON object containing a list of individual incidents. Name is the name of the alert that created the incident.

{
  "incidents": [
    {
      "status": "close",
      "name": "ZK-1 heartbeat",
      "timestamp": "2019-05-23T16:42:24Z",
      "resolution_time": "2019-05-23T17:00:28Z",
      "alert_id": 4823,
      "condition": "Heartbeat: DOWN"
    }
  ],
  "deployment": "ss123456"
}

account > deployment > alerts > read

This method lists the threshold alerts for a deployment. (Alerts are threshold triggers that create incidents.)

GET https://app.searchstax.com/api/rest/v2/account/{account_name}/deployment/{uid}/alerts/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/alerts/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$RESULTS = Invoke-RestMethod -Method Get -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/alerts/" 
$RESULTS = $RESULTS | ConvertTo-Json

The response is a JSON object containing a list of alerts and their properties.

{
  "alerts": [
    {
      "status": "enabled",
      "metric": "system_cpu_usage",
      "max_alerts": 1,
      "threshold": 80.0,
      "host": "ss123456-4",
      "delay_mins": 1,
      "operator": ">",
      "id": 2426,
      "unit": "percentage",
      "name": "High Solr CPU Usage",
      "repeat_every": 1,
      "email": "user@company.com"
    }
  ],
  "deployment": "ss123456"
}

account > deployment > alerts > create

This method creates a new alert in a deployment.

POST https://app.searchstax.com/api/rest/v2/account/{account_name}/deployment/{uid}/alerts/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment.

This method uses Token authentication.

The request body should be a “application/json” encoded object, containing the following items:

{
    "email":  [
                  "user@company.com"
              ],
    "webhook_trigger": 2,
    "webhook_resolve": 5,
    "max_alerts":  "2",
    "metric":  "system_cpu_usage",
    "delay_mins":  "1",
    "name":  "high cpu load",
    "threshold":  "90",
    "operator":  ">",
    "repeat_every":  "5",
    "host":  "*",
    "unit":  "percentage"
}
Parameter Description Example
name
required
string		 Name of the alert. “high cpu load”
metric
required
string		 The metric you wish to monitor. For available metrics, check the Account Alerts Metrics method. “system_cpu_usage”
threshold
required
string		 Alert triggers when it sees threshold events within delay_mins minutes. “90”
unit
required
string		 One of number/percentage/KB/MB/GB percentage
operator
required
string		 One of <,>,>=,<=,= “>”
email
optional
list of strings		 List of email addresses. Either an email or both webhook parameters are required. [“user@company.com”]
webhook_trigger
optional
integer		 The ID of the webhook to call when the alert is triggered. Either an email or both webhook parameters are required. 88
webhook_resolve
optional
integer		 The ID of the webhook to call when the alert is resolved. Either an email or both webhook parameters are required. 99
host
required
string		 Name of the server. Use * to create alerts for all hosts in the cluster. For the Total Requests metric, use the UID of the load balancer. “ss123456-1”
“*”
“ss123456-lb”
delay_mins
required
string		 Alert triggers when it sees threshold events within delay_mins minutes. “5”
max_alerts
required
string		 Maximum number of alerts for this metric. “2”
repeat_every
required
string		 Time interval in mins after which the alert should reset. “10”

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/alerts/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data {
    \"email\": [ \"user@company.com\" ],
    \"max_alerts\":  \"2\",
    \"metric\":  \"system_cpu_usage\",
    \"delay_mins\":  \"1\",
    \"name\":  \"high cpu load\",
    \"threshold\":  \"90\",
    \"operator\":  \">\",
    \"repeat_every\":  \"5\",
    \"host\":  \"*\",
    \"unit\":  \"percentage\"
}

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$body = @{
    name='High Disk Usage'
    metric='system_disk_space_used'
    threshold='50'
    unit='GB'
    operator='>'
    host='*'
    delay_mins='1'
    max_alerts='2'
    repeat_every='5'
    email=@('user@company.com')
    webhook_trigger=2
    webhook_resolve=5
}

$body = $body | ConvertTo-Json

$RESULTS = Invoke-RestMethod -Method Post -Body $body -ContentType 'application/json' -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/alerts/" 
$RESULTS = $RESULTS | ConvertTo-Json

The response is a JSON object containing a simple message.

{
    "message":  "Success!"
}

account > deployment > alerts > update

This method enables or disables an alert (or all alerts) by updating the status property.

PUT /api/rest/v2/account/<account_name>/deployment/<uid>/alerts/<id>|all/

where <account_name> is the name of the tenant account, <uid> is the ID of the deployment, and <id> is the ID number of the alert or “all” to update all deployment alerts simultaneously.

This method uses Token authentication.

The request body should be a “application/json” encoded object, containing the following items:

{
    "status":  "enable"
}
Parameter Description Example
status
required
string		 enable/disable “enable”

When invoked from Linux (Bash script):

curl --request PUT "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/alerts/<id>/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data {
    \"status\":  \"enable\"
}

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"
$ALERTID = "2431"

$body = @{
    status='disable'
}

$body = $body | ConvertTo-Json

$RESULTS = Invoke-RestMethod -Method Put -body $body -ContentType 'application/json' -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/alerts/$ALERTID/" 
$RESULTS = $RESULTS | ConvertTo-Json

The response is a JSON object containing a simple message.

{
  "message": "Disabled alert High Disk Usage",
  "success": "true"
}

account > deployment > alerts > delete

This method deletes an alert (or all alerts) from a deployment.

DELETE /api/rest/v2/account/<account_name>/deployment/<uid>/alerts/<id>|all/

where <account_name> is the name of the tenant account, <uid> is the ID of the deployment, and <id> is the ID number of the alert or “all” to delete all alerts from the deployment.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request DELETE "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/alerts/<id>/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"
$ALERTID = "2431"

$RESULTS = Invoke-RestMethod -Method Delete -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/alerts/$ALERTID/" 
$RESULTS = $RESULTS | ConvertTo-Json

The response is a JSON object containing a simple message.

{
    "message":  "Successfully deleted alert Idle System",
    "success":  "true"
}

account > deployment > alerts > heartbeat > list

This method lists all of the heartbeat alerts for a deployment, along with their properties.

GET /api/rest/v2/account/<account_name>/deployment/<uid>/alerts/heartbeat/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/alerts/heartbeat/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$RESULTS = Invoke-RestMethod -Method Get -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/alerts/heartbeat/" 
$RESULTS = $RESULTS | ConvertTo-Json

The response is a JSON document containing a list of heartbeat alerts and their properties.

{
  "alerts": [
    {
      "status": "enabled",
      "host": "ss123456-1",
      "name": "ZK-1 Heartbeat",
      "interval": 5,
      "id": 341,
      "max_alerts": 1,
      "email": "user@company.com"
    }
  ],
  "deployment": "ss123456"
}

account > deployment > alerts > heartbeat > create

This method creates a heartbeat alert in a deployment.

POST /api/rest/v2/account/<account_name>/deployment/<uid>/alerts/heartbeat/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment.

This method uses Token authentication.

The request body should be a “application/json” encoded object, containing the following items:

{
    "email":  [ "user@company.com" ],
    "name":  "Heartbeat from API",
    "host":  "*",
    "max_alerts":  "5",
    "interval":  "5",
    "webhook_trigger": 2,
    "webhook_resolve": 5
}
Parameter Description Example
name
required
string		 This is the name of the heartbeat alert. “Test Heartbeat”
host
required
string		 This is the host ID, identifying one of the servers of the cluster. Use “*” to place the same alert on all of the cluster’s servers. “ss123456-1” or “*”
interval
required
string		 The number of minutes in the sampling window. The alert will be triggered when SearchStax sees X failures within an Interval of X minutes. Accepts only multiples of 5 minutes up to 30. “5”
max_alerts
required
string		 The maximum number of emails to send about an incident. “5”
email
optional
list of strings		 List of email addresses. Either an email or both webhook parameters are required. [“user@company.com”]
webhook_trigger
optional
integer		 The ID of the webhook to call when the alert is triggered. Either an email or both webhook parameters are required. 88
webhook_resolve
optional
integer		 The ID of the webhook to call when the alert is resolved. Either an email or both webhook parameters are required. 99

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/alerts/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data {
    \"email\": [ \"user@company.com\" ],
    \"max_alerts\":  \"5\",
    \"interval\":  \"5\",
    \"name\":  \"Heartbeat from API\",
    \"host\":  \"*\",
}

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$body = @{
    name='Heartbeat from API'
    host='*'
    interval='5'
    max_alerts='5'
    email=@('user@company.com')
    webhook_trigger=2
    webhook_resolve=5
}

$body = $body | ConvertTo-Json

$RESULTS = Invoke-RestMethod -Method Post -Body $body -ContentType 'application/json' -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/alerts/heartbeat/" 
$RESULTS = $RESULTS | ConvertTo-Json

The response is a JSON document containing a simple success/failure message.

{
    "message":  "Success!"
}

account > deployment > alerts > heartbeat > read

This method retrieves the properties of a heartbeat alert from its ID number.

GET /api/rest/v2/account/<account_name>/deployment/<uid>/alerts/heartbeat/<id>/

where <account_name> is the name of the tenant account, <uid> is the ID of the deployment, and <id> is the ID of the alert. You can obtain the ID from the heartbeat list method.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/alerts/heartbeat/<id>/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"
$ALERTID = "2431"

$RESULTS = Invoke-RestMethod -Method Get -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/alerts/heartbeat/$ALERTID/" 
$RESULTS = $RESULTS | ConvertTo-Json

The response is a JSON document containing the properties of a single heartbeat alert:

{
  "status": "enabled",
  "host": "ss123456-1",
  "name": "ZK-1 Heartbeat",
  "interval": 5,
  "id": 341,
  "max_alerts": 1,
  "email": [
    "user@company.com"
  ]
}

account > deployment > alerts > heartbeat > update

This method enables/disables heartbeat alerts.

PUT /api/rest/v2/account/<account_name>/deployment/<uid>/alerts/heartbeat/<id>/

where <account_name> is the name of the tenant account, <uid> is the ID of the deployment, and <id> is the ID of the alert or “all”. You can obtain the ID from the heartbeat list method.

This method uses Token authentication.

The request body should be a “application/json” encoded object, containing the following items:

{
    "status":  "disable"
}
Parameter Description Example
status
required
string		 enable/disable “enable”

When invoked from Linux (Bash script):

curl --request PUT "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/alerts/heartbeat/<id>/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data {
    \"status\":  \"enable\"
}

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"
$ALERTID = "2431"

$body = @{
    status='disable'
}

$body = $body | ConvertTo-Json

$RESULTS = Invoke-RestMethod -Method Put -body $body -ContentType 'application/json' -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/alerts/heartbeat/$ALERTID/" 
$RESULTS = $RESULTS | ConvertTo-Json

The response is a JSON document describing the success of the action.

{
  "message": "Disabled heartbeat alert for ss123456",
  "success": "true"
}

account > deployment > alerts > heartbeat > delete

This method deletes one or all heartbeat alerts from a deployment.

DELETE /api/rest/v2/account/<account_name>/deployment/<uid>/alerts/heartbeat/<id>/

where <account_name> is the name of the tenant account, <uid> is the ID of the deployment, and <id> is the ID of the alert or “all”. You can obtain the ID from the heartbeat list method.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request DELETE "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/alerts/heartbeat/<id>/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"
$ALERTID = "2431"

$RESULTS = Invoke-RestMethod -Method Delete -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/alerts/heartbeat/$ALERTID/" 
$RESULTS = $RESULTS | ConvertTo-Json

The response is a JSON document confirming the success of the deletion.

{
    "message":  "Successfully deleted all heartbeat alerts for ss123456",
    "success":  "true"
}

Questions?

Do not hesitate to contact the SearchStax Support Desk.