SearchStax Provisioning API

Overview

SearchStax^® provides an API supporting the creation and deletion of SearchStax deployments. 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.

The core of the API is devoted to helper functions that expose parameters required by the provisioning operations. These functions are presented first in the order you would utilize them. The remaining functions are presented in groups related by task.

Contents:

API Termination Protection
Metavariable Notation
Authentication
Deployment
Tags
Alerts
Zookeeper

API Termination Protection

The authorized users of your SearchStax account can access the SearchStax API, and use it to provision and terminate deployments.

It is possible for the account Admins to shield specific deployments from API deletion. On the Deployment's details page, look for the API Termination Protection button. Click the button to protect the deployment from API deletion. SearchStax API Termination Protection Lock This lock gives the Admin some peace of mind while developers experiment with the API. Non-Admin users cannot set or remove this protection.

Metavariable Notation

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

Authentication

The Provisioning API uses two methods of authentication appropriate to two levels of security:

Token Authentication: Use the username and password of an authorized user to obtain an authentication token. The token authorizes API calls within the normal scope of the user's permissions. A token expires after 24 hours.
API Key Authentication: The API Key authenticates a narrow set of API functions for managing Solr Basic Auth users and Zookeeper configurations in a deployment. The API Key does not expire, but it can be revoked.

Token Authentication

The first step in using the SearchStax API is to obtain an authentication token by logging in to the SearchStax server. The token authorizes subsequent API requests.

obtain-auth-token > create

Generates an authentication token for the user of a tenant account. This token can be used to authenticate Searchstax API calls for up to 24 hours.

POST https://app.searchstax.com/api/rest/v2/obtain-auth-token/

The request body should be an "application/x-www-form-urlencoded" object to accommodate the non-alphanumeric characters that sometimes appear in user names and passwords.

"username=<username>&password=<password>"

Parameter	Description	Example
username required string	This is the email address used when you log into the SearchStax server.	"user@company.com"
password required string	This is the password associated with that username.	"4r36%74m"

When invoked from Linux (Bash script):

TOKEN=$(curl -s -H "Content-Type: application/json" -X POST \
       -d "{\"username\":\"$USER\",\"password\":\"$PASSWORD\"}" \
       https://app.searchstax.com/api/rest/v2/obtain-auth-token/)

When invoked from Windows (PowerShell script):

$body = @{
    username=$USER
    password=$PASSWORD
}

$body = $body | ConvertTo-Json

$TOKEN = Invoke-RestMethod -Method Post -Body $body -ContentType 'application/json' `
        -uri "https://app.searchstax.com/api/rest/v2/obtain-auth-token/"

The response is a JSON document containing an authorization token.

{
  "token": "aa70cb0a180a0532ae8855f7a1712eeceb81e080"
}

Using the token in Bash

In the Bash scripts, the authorization token is incorporated directly in the header of the cURL call:

    curl -s -H "Authorization: Token $TOKEN" etc.

Using the token in PowerShell

In the PowerShell scripts, we use the token by assembling a header and using it in the Invoke-RestMethod call:

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Authorization", "Token $TOKEN")
$RESULTS = Invoke-RestMethod -Headers $headers etc.

API Key Authentication

An API Key is a non-expiring authorization giving an external user a limited ability to manage his own Zookeeper configurations and Solr Basic Auth users. It is created by a SearchStax Admin using an Authentication Token.

account > apikey > create

This method creates an API Key based on a valid authentication token.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/

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

This method uses Token authentication.

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

{
    "scope":["deployment.dedicateddeployment"]
}

Parameter	Description
scope required list of strings	The scope in which this API key will be effective. Default value is deployment.dedicateddeployment.

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data "{
    \"scope\":[\"deployment.dedicateddeployment\"]
}"

When invoked from Windows (PowerShell script):

$body = @{
    scope=@('deployment.dedicateddeployment')   # Force single-value to be a list
}
$body = $body | ConvertTo-Json

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

The response is a JSON document:

{ "apikey": "eyJhbGciOiJIUzVCJ9.eyJpYXQiOjE1NDMyNDc0ODMsImp0aSI6IjhmYTlkZThjNTIyNjRjZTc2Njg0NTkyMWQ4MTQ0MDY5ZThkMjc5NmMiLCJzY29wZSI6WyJkZXBsb3ltZW50LmRlZGljYXRlZGRlcGxveW1lbnQiXSwiQ1MrdThSZmlNTzMwNnZJM082QSJ9.r6X7bJi_ZWGR99XC0Ac" }

Using the API key in Bash

In the Bash scripts, we use the API key directly in the header of the cURL call:

    curl -s -H "Authorization: APIkey $APIKEY" etc.

Using the API key in PowerShell

In the PowerShell scripts, we use the API key by assembling a header and using it in the Invoke-RestMethod call:

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Authorization", "APIkey $APIKEY")
$RESULTS = Invoke-RestMethod -Headers $headers etc.

account > apikey > associate_apikey_to_deployment

This method associates an API key to a specific deployment. Note that an API key can be associated with multiple deployments, but each deployment can be associated with only one API key at a time.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/associate/

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

This method requires Token authentication.

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

{
    "apikey": "XYZ.ABC123",
    "deployment": "ss244503"
}

Parameter	Description	Example
apikey required string	This is the API key that needs to be associated with the deployment.	"XYZ.ABC123"
deployment required string	This is the UID of the deployment.	"ss244503"

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/associate/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data "{
    \"apikey\": \"XYZ.ABC123\",
    \"deployment\": \"ss244503\"
}"

When invoked from Windows (PowerShell script):

$body = @{
    apikey=$APIKEY
    deployment=$uid
}

$body = $body | ConvertTo-Json

$RESULT = Invoke-RestMethod  -Method Post -body $body -ContentType 'application/json' -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/apikey/associate/"

$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document containing a list of deployments associated with this key.

{
  "deployments": [ "ssXXXXX1", "ssXXXXX2"]
}

account > apikey > apikey_deployments

This method lists the deployments associated with the given API key.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/deployments/

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

This method uses Token authentication.

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

{
    "apikey" : "XYZ.ABC123"
}

Parameter	Description	Example
apikey required string	This is the API key that is associated with the deployments.	"XYZ.ABC123"

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/deployments/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data "{ \"apikey\" : \"XYZ.ABC123\" }"

When invoked from Windows (PowerShell script):

$body = @{
    apikey=$APIKEY
}

$body = $body | ConvertTo-Json

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

The response is a JSON document containing a list of deployment UIDs.

{
  "deployments": [ "ssXXXXX1" ]
}

account > apikey > disassociate_apikey_from_deployment

This method disassociates an API key from a deployment.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/disassociate/

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

This method uses Token authentication.

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

{
    "apikey" : "XYZ.ABC123",
    "deployment": "ss244503"
}

Parameter	Description	Example
apikey required string	This is the API key that needs to be disassociated from the deployment.	"XYZ.ABC123"
deployment required string	This is the UID of the deployment.	"ss244503"

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/disassociate/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data "{
    \"apikey\" : \"XYZ.ABC123\",
    \"deployment\": \"ss244503\"
}"

When invoked from Windows (PowerShell script):

$body = @{
    apikey=$APIKEY
    deployment=$uid
}

$body = $body | ConvertTo-Json

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

The response is a JSON document containing a list of deployments with which the API key is still associated.

{
  "deployments": [
    "ss213022",
    "ss490103",
    "ss644170"
  ]
}

account > apikey > deployment_apikeys

This method lists the API key that is associated with a deployment. Each deployment may be associated with only one API key at a time.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/list/

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

This method uses Token authentication.

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

{
    "deployment" : "ss244503"
}

Parameter	Description	Example
deployment required string	This is the UID of the deployment.	"ss244503"

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/list/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data "{ \"deployment\" : \"ss244503\" }"

When invoked from Windows (PowerShell script):

$body = @{
    deployment=$uid
}

$body = $body | ConvertTo-Json

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

The response is a JSON document containing the API key associated with the deployment.

{
  "apikey": [ "eyJhbGciOiJI6IkpXVCJ9..." ]
}

account > apikey > revoke

This method revokes an API key.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/revoke/

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

This method uses Token authentication.

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

{
    "apikey" : "XYZ.ABC123"
}

Parameter	Description	Example
apikey required string	This is the API key to revoke.	"XYZ.ABC123"

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/revoke/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data "{
    \"apikey\" : \"XYZ.ABC123\"
}"

When invoked from Windows (PowerShell script):

$body = @{
    apikey=$APIKEY
}

$body = $body | ConvertTo-Json

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

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

{
  "success": "API Key revoked successfully."
}

Solr Basic Auth

The SearchStax Provisioning API provides a selection of methods for managing Solr basic authentication from a remote application.

account > deployment > solr > auth > enable_basic_auth

This method enables basic auth for a Solr deployment.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/auth/enable/

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

This method uses either Token authentication or API key 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>/solr/auth/enable/" \
  --header "Authorization: APIkey <apikey>"

When invoked from Windows (PowerShell script):

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

This method returns a JSON document containing a success message.

{
  "message": "Basic authentication successfully Enabled for Solr",
  "success": "true"
}

account > deployment > solr > auth > disable_basic_auth

This method disables basic auth for a Solr deployment.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/auth/disable/

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

This method uses either Token authentication or API key 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>/solr/auth/disable/" \
  --header "Authorization: APIkey <apikey>" \

When invoked from Windows (PowerShell script):

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

This method returns a JSON document containing a success message.

{
  "message": "Basic authentication successfully Disabled for Solr",
  "success": "true"
}

account > deployment > solr > auth > add_solr_user

This method adds a Solr user to the deployment. Basic auth must be enabled.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/auth/add-user/

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

This method uses either Token authentication or API key authentication.

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

{
    "username" : "demoSolrUser",
    "password" : "test123",
    "role" : "Admin"
}

Parameter	Description	Example
username required string	This is the Solr user name.	"demoSolrUser"
password required string	This is the Solr user's password.	"test123"
role required string	This is the Solr role: Admin, Read, or Write.	"Admin"

See Solr Basic Authentication for an explanation of the Solr roles.

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/auth/add-user/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data "{
    \"username\" : \"demoSolrUser\",
    \"password\" : \"test123\",
    \"role\" : \"Admin\"
}"

When invoked from Windows (PowerShell script):

$body = @{
    username='demoSolrUser'
    password='test123'
    role='Admin'
}

$body = $body | ConvertTo-Json

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

This method returns a JSON document containing a success message.

{
  "message": "User successfully added",
  "success": "true"
}

account > deployment > solr > auth > delete_solr_user

This method deletes a Solr user from a deployment.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/auth/delete-user/

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

This method uses either Token authentication or API key authentication.

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

{
    "username" : "demoSolrUser"
}

Parameter	Description	Example
username required string	This is the Solr user name.	"demoSolrUser"

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/auth/delete-user/" \
  --header "Authorization: APIkey <apikey>" \
  --header "Content-Type: application/json" \
  --data "{
    \"username\" : \"demoSolrUser\"
}"

When invoked from Windows (PowerShell script):

$body = @{
    username='demoSolrUser'
}

$body = $body | ConvertTo-Json

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

This method returns a JSON document containing a success message.

{
  "message": "User successfully deleted!",
  "success": "true"
}

account > deployment > solr > auth > get_solr_users

This method gets the Solr users for a deployment.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/auth/get-users/

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

This method uses either Token authentication or API key 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>/solr/auth/get-users/" \
  --header "Authorization: APIkey <apikey>"

When invoked from Windows (PowerShell script):

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

The response is a JSON document containing the Solr users and the roles associated with them.

{
  "users": {
    "demoSolrUser": {
      "roles": "Read Write Admin"
    }
  },
  "success": "true"
}

account > deployment > solr > auth > set_solr_user_password

This method sets a password for a Solr user.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/auth/set-password/

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

This method uses either Token authentication or API key authentication.

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

{
    "username" : "demoSolrUser",
    "password": "test456"
}

Parameter	Description	Example
username required string	This is the Solr user name.	"demoSolrUser"
password required string	This is the Solr user's password.	"test456"

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/auth/set-password/" \
  --header "Authorization: APIkey <apikey>" \
  --header "Content-Type: application/json" \
  --data "{
    \"username\" : \"demoSolrUser\",
    \"password\": \"test456\"
}"

When invoked from Windows (PowerShell script):

$body = @{
    username='demoSolrUser'
    password='test456'
}

$body = $body | ConvertTo-Json

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

This method returns a JSON document containing a success message.

{
  "message": "Password successfully updated!",
  "success": "true"
}

account > deployment > solr > auth > set_solr_user_role

This method sets the Solr user's role. Available roles are Admin, Read, and Write.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/auth/set-role/

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

This method uses either Token authentication or API key authentication.

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

{
    "username" : "demoSolrUser",
    "role" : "Read"
}

Parameter	Description	Example
username required string	This is the Solr user name.	"demoSolrUser"
role required string	This is the Solr role: Admin, Read, or Write.	"Read"

See Solr Basic Authentication for an explanation of the Solr roles.

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/auth/set-role/" \
  --header "Authorization: APIkey <apikey>" \
  --header "Content-Type: application/json" \
  --data "{
    \"username\" : \"demoSolrUser\",
    \"role\" : \"Read\"
}"

When invoked from Windows (PowerShell script):

$body = @{
    username='demoSolrUser'
    role='Read'
}

$body = $body | ConvertTo-Json

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

This method returns a JSON document containing a success message.

{
  "message": "Successfully updated user role!",
  "success": "true"
}

Deployment

This section of the SearchStax Provisioning API lets you create and delete deployments, list deployments, get the health status of a deployment, and list the SearchStax plans for creating a new deployment.

account > deployment > create

This method lets you create a new deployment. Note that a successful response indicates only that deployment creation was successfully authorized and has begun. It can take up to an hour to bring a new deployment on line depending on the cloud provider.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/

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

This method uses Token authentication.

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

{
    "name": "DN4_azure_api_2",
    "application": "Solr",
    "application_version": "7.3.1",
    "termination_lock": false,
    "plan_type": "DedicatedDeployment",
    "plan": "DN4",
    "region_id": "eastus",
    "cloud_provider_id": "azure",
    "num_additional_app_nodes": 0
}

Parameter	Description	Example
name required string	The name of the new deployment	"DN4_azure_api_2"
application required string	The application for which this deployment is being created.	"Solr"
application_version required string	The version of application being deployed. Detailed information regarding application versions is available from the List Plans method.	"7.3.1"
termination_lock required boolean	Whether or not the deployment should be shielded from API deletion.	false
plan_type required string	Available plan type could be Shared Deployment or Dedicated Deployment. Currently SearchStax only supports Dedicated Deployment (the default).	"DedicatedDeployment"
plan required string	The plan of the selected plan type. Detailed information regarding plans available can be fetched using List Plans method.	"DN4"
region_id required string	The region ID of the region where deployment has to be created. Detailed information regarding regions available can be fetched using List Plans method.	"eastus"
cloud_provider_id required string	The cloud provider to be used to create this deployment. Detailed information regarding cloud providers available can be fetched using List Plans method.	"aws" "azure" "gcp"
num_additional_app_nodes optional number	The number of additional nodes to be added to the deployment in case you want to add nodes to a dedicated cluster's default 3 nodes.	"0"

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/" \
  --header "Content-Type: application/json" \
  --header "Authorization: Token <token>" \
  --data "{
    \"name\": \"DN4_azure_api_2\",
    \"application\": \"Solr\",
    \"application_version\": \"7.3.1\",
    \"termination_lock\": false,
    \"plan_type\": \"DedicatedDeployment\",
    \"plan\": \"DN4\",
    \"region_id\": \"eastus\",
    \"cloud_provider_id\": \"azure\",
    \"num_additional_app_nodes\": \"0\"
    }"

When invoked from Windows (PowerShell script):

$body = @{
    name='SolrFromAPI'
    application='Solr'
    application_version='7.5.0'
    termination_lock='false'
    plan_type='DedicatedDeployment'
    plan='DN1'
    region_id='us-west-1'
    cloud_provider_id='aws'
    num_additional_app_nodes='0'
}

$body = $body | ConvertTo-Json

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

The response is a JSON document containing ...

{
  "name": "SolrFromAPI",
  "uid": "ss460929",
  "application": "Solr",
  "application_version": "7.5.0",
  "tier": "Silver",
  "http_endpoint": null,
  "status": "Pending",
  "provision_state": "Pending",
  "termination_lock": false,
  "plan_type": "DedicatedDeployment",
  "plan": "DN1",
  "region_id": "us-west-1",
  "cloud_provider": "Amazon Web Services",
  "cloud_provider_id": "aws",
  "num_additional_app_nodes": 0,
  "deployment_type": "Dedicated Node",
  "num_nodes_default": 1,
  "num_zookeeper_nodes_default": 0,
  "num_additional_zookeeper_nodes": 0,
  "servers": [],
  "zookeeper_ensemble": null,
  "tag": [],
  "specifications": {
    "disk_space": "8589934592",
    "jvm_heap_memory": "536870912",
    "physical_memory": "1073741824"
  }
}

Note that the servers and the zookeeper_ensemble values are not initially available because those entities take time to create. Wait until the deployment is up and running, and then use the account > deployment > list method (below).

account > deployment > delete

This method deletes a deployment from the tenant account. Note that a successful response means only that the deletion process was authorized and has begun. It can take up to an hour to delete a deployment depending on the cloud provider.

DELETE https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/

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 DELETE "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$RESULT = Invoke-RestMethod -Method Delete -ContentType 'application/json' -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/SilverQAAccount/deployment/$uid/" 
$RESULT = $RESULT | ConvertTo-Json

A success response will contain a blank response with 200 status. Invalid UID will throw a Not Found error.

{
  "detail": "Not found."
}

account > deployment > list

This method lists the deployments of an account along with their deployment details.

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

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>/deployment/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$DEPLOYMENTS = Invoke-RestMethod -Method Get -ContentType 'application/json' -Headers $headers `
              -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/" 
$DEPLOYMENTS = $DEPLOYMENTS | ConvertTo-Json

A successful response contains a JSON object containing a list of deployment descriptions:

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "name": "solr-7-5-dc4",
      "uid": "ss137722",
      "application": "Solr",
      "application_version": "7.5.0",
      "tier": "Silver",
      "http_endpoint": "https://ss137722-us-east-1-aws.searchstax.com/solr/",
      "status": "Running",
      "provision_state": "Done",
      "termination_lock": false,
      "plan_type": "DedicatedDeployment",
      "plan": "DC4",
      "region_id": "us-east-1",
      "cloud_provider": "Amazon Web Services",
      "cloud_provider_id": "aws",
      "num_additional_app_nodes": 0,
      "deployment_type": "Dedicated Cluster",
      "num_nodes_default": 3,
      "num_additional_zookeeper_nodes": 0,
      "servers": [
        "ss137722-3",
        "ss137722-2",
        "ss137722-1"
      ],
      "zookeeper_ensemble": "ss137722-1-us-east-1-aws.searchstax.com:2181,ss137722-2-us-east-1-aws.searchstax.com:2181,ss137722-3-us-east-1-aws.searchstax.com:2181",
      "tag": [
        "metrics-api",
        "user:dipsy"
      ],
      "specifications": {
        "disk_space": "34359738368",
        "jvm_heap_memory": "2147483648",
        "physical_memory": "4294967296"
      }
    }, <plus more deployments, if any...>

account > deployment > read

This method lists the properties of a specific deployment.

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

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>/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

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

The response is a JSON document containing the detailed properties of a deployment:

{
  "name": "Script-Testing",
  "uid": "ss213022",
  "application": "Solr",
  "application_version": "7.5.0",
  "tier": "Silver",
  "http_endpoint": "https://ss213022-v3xqvj5e-us-west-1-aws.searchstax.com/solr/
",
  "status": "Running",
  "provision_state": "Done",
  "termination_lock": false,
  "plan_type": "DedicatedDeployment",
  "plan": "NDC4",
  "region_id": "us-west-1",
  "cloud_provider": "Amazon Web Services",
  "cloud_provider_id": "aws",
  "num_additional_app_nodes": 0,
  "deployment_type": "Dedicated Cluster",
  "num_nodes_default": 2,
  "num_zookeeper_nodes_default": 3,
  "num_additional_zookeeper_nodes": 0,
  "servers": [
    "ss213022-5",
    "ss213022-4",
    "ss213022-3",
    "ss213022-2",
    "ss213022-1"
  ],
  "zookeeper_ensemble": "ss213022-v3xqvj5e-1-us-west-1-aws.searchstax.com:2181,s
s213022-v3xqvj5e-2-us-west-1-aws.searchstax.com:2181,ss213022-v3xqvj5e-3-us-west
-1-aws.searchstax.com:2181",
  "tag": [],
  "specifications": {
    "disk_space": "34359738368",
    "jvm_heap_memory": "2147483648",
    "physical_memory": "4294967296"
  }
}

Converting specifications to GB

In a PowerShell script, we can convert the reported specification values to GB using the following lines. Do not convert the output to JSON before making these calculations:

$GB = [math]::pow( 1024, 3 ) # To convert raw memory to rounded GB like the UI uses. $DISK = $DETAILS.specifications.disk_space / $GB $JVM = $DETAILS.specifications.jvm_heap_memory / $GB $MEMORY = $DETAILS.specifications.physical_memory / $GB

Write-Host "Disk space is $DISK GB" Write-Host "JVM heap memory is $JVM GB" Write-Host "Physical memory is $MEMORY GB"

account > deployment > get_deployment_health

This method gets the deployment's health using its UID.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/deployment-health/

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>/deployment-health/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

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

Responses are JSON documents like those shown below. These examples are from a three-node cluster:

All nodes are running.
{ "status": "OK", "level": "success" }
One or two of the three servers is down.
{ "status": "Warn", "level": "warning" }
All three servers are down.
{ "status": "Error", "level": "danger" }
Invalid UID throws a Not Found error.
{ "detail": "Not found." }

account > plan > list

This method lists the available deployment plans and the regions where those plans are available.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/plan/?page=1&application=solr&plan_type=DedicatedPlan

where <account_name> is the name of the tenant account. There are three query parameters: page is the page number within the paginated result set; application requests plans for either "solr" or "elasticsearch"; and plan_type is "DedicatedPlan". (The API currently supports only one plan type.)

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>/plan/?page=1&application=solr&plan_type=DedicatedPlan" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$RESULT = Invoke-RestMethod -Method Get -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/plan/?page=1&application=solr&plan_type=DedicatedPlan" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document with the following values -

Key	Value	Example
name "string"	The name of the plan	"DN4"
description "string"	The description of the plan.	"4GB memory, 32GB storage"
application "object"	JSON object with details of application selected	`{ "name": "Solr", "description": "Apache Solr", "tag": "solr" }`
application_versions "list of strings"	List of available application versions	["7.3.1", "7.2.1"]
plan_type "string"	The plan type selected	"DedicatedPlan"
plan_regions "list of objects"	List of objects containing information about Cloud provider Region ID Additional application node price Price Cloud provider ID Additional zookeeper node price	`{ "cloud_provider": "Microsoft Azure", "region_id": "centralus", "additional_application_node_price": 312, "price": 312, "cloud_provider_id": "azure", "additional_zookeeper_node_price": 0 }`
trial_available "boolean"	Whether the plan is available in trial account	false

account > usage > list

This method produces a list of an account's billable usage events during a specific year and month.

GET /api/rest/v2/account/<account_name>/usage/<year>/<month>/

where <account_name> is the name of the tenant account, <year> is an integer (2019), and <month> is an integer (1-12).

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>/usage/<year>/<month>/ \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

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

The response is a JSON document containing a list of usage events like this one:

  {
    "SKU": "DN4",
    "startDate": "2019-04-01",
    "endDate": "2019-04-30",
    "objectID": "ss123456",
    "currency": "USD",
    "amount": "192.00",
    "usage": 30,
    "tagCollection": []
  },

Usage is the number of billable days between startDate and endDate, inclusively. In the case of backup storage, it is the number of bytes stored.

Parameter	Description	Example
tags required list of strings	A list of tags to add to the deployment.	["demo", "test"]

Parameter	Description	Example
tags required list of strings	A list of tags to delete.	["test"]

Parameter	Description	Example
tags required list of strings	A list of tags to match.	["demo", "test"]
operator required string	Operator to apply to the matches.	"AND"/"OR"

Alerts

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

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):

$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):

$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": "ss213022"
}

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):

$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": "ss416352-4",
      "delay_mins": 1,
      "operator": ">",
      "id": 2426,
      "unit": "percentage",
      "name": "High Solr CPU Usage",
      "repeat_every": 1,
      "email": "bruce@searchstax.com"
    }
  ],
  "deployment": "ss416352"
}

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":  [
                  "bruce@searchstax.com"
              ],
    "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 required list of strings	List of email addresses	["bruce@searchstax.com"]
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.	"ss791863-1" "*" "ss791863-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\": [ \"bruce@searchstax.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):

$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=@('bruce+null@searchstax.com')
}

$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):

$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):

$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):

$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": "ss416352-1",
      "name": "ZK-1 Heartbeat",
      "failures": 1,
      "interval": 1,
      "id": 341,
      "max_alerts": 1,
      "email": "bruce+null@searchstax.com"
    }
  ],
  "deployment": "ss416352"
}

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":  [ "bruce@searchstax.co" ],
    "name":  "Heartbeat from API",
    "host":  "*",
    "failures":  "1",
    "max_alerts":  "5",
    "interval":  "2"
}

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.	"ss927085-1" or "*"
failures required string	The number of failures. The alert will be triggered when SearchStax sees X Failures within an Interval of Y minutes.	"2"
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 Y minutes.	"5"
max_alerts required string	The maximum number of emails to send about an incident.	"5"
email required list of strings	List of email addresses to be notified of an incident.	["bruce@searchstax.com"]

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\": [ \"bruce@searchstax.com\" ],
    \"max_alerts\":  \"5\",
    \"interval\":  \"2\",
    \"name\":  \"Heartbeat from API\",
    \"failures\":  \"1\",
    \"host\":  \"*\",
}

When invoked from Windows (Powershell script):

$body = @{
    name='Heartbeat from API'
    host='*'
    failures='1'
    interval='2'
    max_alerts='5'
    email=@('bruce@searchstax.com')
}

$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):

$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": "ss416352-1",
  "name": "ZK-1 Heartbeat",
  "failures": 1,
  "interval": 1,
  "id": 341,
  "max_alerts": 1,
  "email": [
    "bruce+null@searchstax.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):

$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 ss416352",
  "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):

$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 ss475684",
    "success":  "true"
}

Zookeeper

The Provisioning API includes methods for accessing Zookeeper configuration sets.

account > deployment > zookeeper-config > list

This method returns a list of named configurations from a Zookeeper ensemble.

GET /api/rest/v2/account/<account_name>/deployment/<uid>/zookeeper-config/?page=<n>

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment. The query parameter page is a number, <n>, that defaults to 1.

This method uses either Token authentication or API key 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>/zookeeper-config/?page=<n>" \
  --header "Authorization: APIkey <apikey>"

When invoked from Windows (PowerShell script):

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

The response is a JSON document containing a list of Zookeeper configurations.

{
    "configs":  [
                    "_default",
                    "film"
                ],
    "success":  "true"
}

account > deployment > zookeeper-config > create

This method lets you upload a configset to the Zookeeper ensemble of a deployment.

POST /api/rest/v2/account/<account_name>/deployment/<uid>/zookeeper-config/

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

This method uses either Token authentication or API key authentication.

The request body should be a "multipart/form-data" encoded object, containing the following items:

Parameter	Description	Example
name required string	This is the name of the new Zookeeper config.	"text_config"
files required file	The value here is the path to a zip file of the contents of a local config directory.	@conf.zip

The config files are uploaded as a zip file including the contents of the configuration directory but not the directory itself. The zip file should contain all configuration files, including subfolders.

SearchStax Provisioning API

When invoked from Linux (Bash script), use the -F, --form <name=content> param to specify name and files. This enables uploading of binary files. To force the zip file to be uploaded as a binary file, prefix the file name with an "@" character.

curl -H "Authorization: APIkey <apikey>" \ 
   -X POST \
   -F "name=test_config" \
   -F "files=@conf.zip" \
   https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/zookeeper-config/

When invoked from Windows (PowerShell script), you must use PowerShell Core 6.1+. We used Version 6.2. To determine what version of PowerShell you are running, evaluate $PSVersionTable.PSVersion. Version 6.2 may be downloaded from GitHub.

$form = @{
    name = 'test_config'
    files = Get-Item -Path 'conf.zip'
}

# Assuming the zipped config file is in the same directory as this script. 

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

The response is a JSON document containing a list of the deployment's current configsets.

{
  "configs": [
    "_default",
    "film",
    "test_config"
  ],
  "success": "true"
}

account > deployment > zookeeper-config > read

This method returns a list of config files from a named configuration in the Zookeeper ensemble of a deployment.

GET /api/rest/v2/account/<account_name>/deployment/<uid>/zookeeper-config/<name>/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment. The <name> is the name of a configuration within Zookeeper.

This method uses either Token authentication or API key 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>/zookeeper-config/<name>/" \
  --header "Authorization: APIkey <apikey>"

When invoked from Windows (PowerShell script):

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

The response is a JSON document containing a list of all files in the configset.

{
  "configs": [
    "film/lang/hyphenations_ga.txt",
    "film/lang/stopwords_hu.txt",
    "film/lang/stopwords_el.txt",
    "film/lang/stopwords_no.txt",
    "film/lang/stopwords_ca.txt",
    "film/lang/stopwords_de.txt",
    "film/lang/stopwords_sv.txt",
    "film/stopwords.txt",
    "film/lang/contractions_ca.txt",
    "film/lang/stopwords_ro.txt",
    "film/lang/stopwords_bg.txt",
    "film/solrconfig.xml",
    "film/lang/stopwords_ga.txt",
    "film/lang/stopwords_en.txt",
    "film/lang/stopwords_es.txt",
    "film/lang/stopwords_gl.txt",
    "film/lang/stopwords_fi.txt",
    "film/lang/contractions_fr.txt",
    "film/lang/stopwords_da.txt",
    "film/lang/stopwords_fa.txt",
    "film/lang/stopwords_nl.txt",
    "film/lang/stopwords_it.txt",
    "film/lang/stopwords_pt.txt",
    "film/params.json",
    "film/protwords.txt",
    "film/lang/stoptags_ja.txt",
    "film/lang/userdict_ja.txt",
    "film/lang/stopwords_tr.txt",
    "film/lang/stopwords_ru.txt",
    "film/lang/contractions_ga.txt",
    "film/synonyms.txt",
    "film/lang/stopwords_fr.txt",
    "film/lang/stopwords_ar.txt",
    "film/lang/stopwords_eu.txt",
    "film/lang/stopwords_th.txt",
    "film/lang/stopwords_hy.txt",
    "film/lang/stopwords_lv.txt",
    "film/lang/stemdict_nl.txt",
    "film/lang/contractions_it.txt",
    "film/lang/stopwords_hi.txt",
    "film/lang/stopwords_ja.txt",
    "film/lang/stopwords_cz.txt",
    "film/managed-schema",
    "film/lang/stopwords_id.txt"
  ],
  "name": "test_config",
  "success": "true"
}

account > deployment > zookeeper-config > delete

This method deletes a configset from the Zookeeper ensemble of a deployment.

DELETE /api/rest/v2/account/<account_name>/deployment/<uid>/zookeeper-config/<name>/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment. The <name> is the name of a configuration within Zookeeper.

This method uses either Token authentication or API key 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>/zookeeper-config/<name>/" \
  --header "Authorization: APIkey <apikey>"

When invoked from Windows (PowerShell script):

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

The response is a JSON document containing a confirmation message.

{
    "message":  "Config test_config has been deleted.",
    "success":  "true"
}

account > deployment > zookeeper-config > download

This method downloads a configset from the Zookeeper ensemble of a deployment in the form of a zip file.

GET /api/rest/v2/account/<account_name>/deployment/<uid>/zookeeper-config/<name>/download/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment. The <name> is the name of a configuration within Zookeeper.

This method uses either Token authentication or API key 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>/zookeeper-config/<name>/download/" \
  --header "Authorization: APIkey <apikey>" 
  -o "filename.zip"

Note the -o "filename.zip" parameter in cURL. This captures the downloaded zip file and writes it to the current directory.

When invoked from Windows (PowerShell script):

$RESULTS = Invoke-RestMethod -outfile "$NAME.zip" -Method Get -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/zookeeper-config/$NAME/download/" 
Write-Host "Look for $NAME.zip in current directory."

Note the -outfile "$NAME.zip" parameter in Invoke-RestMethod. This captures the downloaded zip file and writes it to the current directory.

The response is a zip file containing the configset files from Zookeeper.

Questions?

Do not hesitate to contact the SearchStax Support Desk.

Free Trial

Tutorials/Guides

Cloud Manager

Private Cloud

Pulse/Monitoring

Search Analytics

SearchStax API

Third-Party Integration

Accounts and Billing

Support Guide

SearchStax Provisioning API

Overview

API Termination Protection

Metavariable Notation

Authentication

Token Authentication

obtain-auth-token > create

API Key Authentication

account > apikey > create

account > apikey > associate_apikey_to_deployment

account > apikey > apikey_deployments

account > apikey > disassociate_apikey_from_deployment

account > apikey > deployment_apikeys

account > apikey > revoke

Solr Basic Auth

account > deployment > solr > auth > enable_basic_auth

account > deployment > solr > auth > disable_basic_auth

account > deployment > solr > auth > add_solr_user

account > deployment > solr > auth > delete_solr_user

account > deployment > solr > auth > get_solr_users

account > deployment > solr > auth > set_solr_user_password

account > deployment > solr > auth > set_solr_user_role

Deployment

account > deployment > create

account > deployment > delete

account > deployment > list

account > deployment > read

account > deployment > get_deployment_health

account > plan > list

account > usage > list

Tags

account > deployment > tags > create

account > deployment > tags > delete

account > deployment > tags > list

account > deployment > tags > get_deployments

Alerts

account > alerts > metrics

account > deployment > incidents

account > deployment > alerts > read

account > deployment > alerts > create

account > deployment > alerts > update

account > deployment > alerts > delete

account > deployment > alerts > heartbeat > list

account > deployment > alerts > heartbeat > create

account > deployment > alerts > heartbeat > read

account > deployment > alerts > heartbeat > update

account > deployment > alerts > heartbeat > delete

Zookeeper

account > deployment > zookeeper-config > list

account > deployment > zookeeper-config > create

account > deployment > zookeeper-config > read

account > deployment > zookeeper-config > delete

account > deployment > zookeeper-config > download

Questions?