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 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.

Create Auth Token

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

curl --request POST "https://app.searchstax.com/api/rest/v2/obtain-auth-token/" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "username=<username>&password=<password>"

The response is a JSON document containing an authorization token.

{
  "token": "aa70cb0a180a0532ae8855f7a1712eeceb81e080"
}

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.

Create API Key

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

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\"]
}"

The response is a JSON document:

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

Associate API Key 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 cURL:

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\"
}"

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

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

API Key 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 cURL:

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\"
}"

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

{
  "deployments": [ "ssXXXXX1" ]
}

Disassociate API Key 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 cURL:

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\"
}"

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

{
  "deployments": []
}

Deployment API Key

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

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\"
}"

The response is a JSON document containing a list of API keys associated with the deployment.

{
  "Apikey": [ "eyJhbGciOiJI6IkpXVCJ9.eyJpYXQiOjE1NDMRmZTVlZWI3MzZjZjgzZmIiLCJzY29wZSI6WyJkZXBsb3ltZW50LmRlZGljYXRlZGRlcGxveW1lbnQiXSwidGVuYW50X2FwaV9hY2Nlc3Nfa2V5IjoiMk9PQ1MrdThSZmlNTzMwNnZJM082QSJ9.NTDaGV1oo0kHaCSRds" ]
}

Revoke API Key

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

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\"
}"

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.

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

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/auth/enable/" \
  --header "Authorization: APIkey <apikey>"

This method returns a blank response with a 200 status message.

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

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/auth/disable/" \
  --header "Authorization: APIkey <apikey>" \

This method returns a blank response with a 200 status message.

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

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\"
}"

This method returns a text response with a 201 status message on successful user creation.

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

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\"
}"

This method returns a text response with 200 status message on successful user deletion.

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

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/auth/get-users/" \
  --header "Authorization: APIkey <apikey>"

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

{
  "demoSolrUser": { "roles": ["Read","Write","Admin"] }
}

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": "test123"
}

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

When invoked from cURL:

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\": \"test123\"
}"

This method returns a text response with a 200 status message on successful password change.

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.	"Admin"

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

When invoked from cURL:

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\"
}"

This method returns a text response with a 200 status message on successful user modification.

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.

Create Deployment

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

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\"
    }"

The response is a JSON document containing ...

{
  "name": "DN4_azure_api_2", 
  "uid": "ssXXXXX", 
  "application": "Solr", 
  "application_version": "7.3.1", 
  "tier": "Silver", 
  "http_endpoint": null, 
  "status": "Pending", 
  "provision_state": "Pending", 
  "termination_lock": false, 
  "plan_type": "DedicatedDeployment", 
  "plan": "DN4", 
  "region_id": "eastus", 
  "cloud_provider": "Microsoft Azure", 
  "cloud_provider_id": "azure", 
  "num_additional_app_nodes": 0, 
  "deployment_type": "Dedicated Node", 
  "num_nodes_default": 1, 
  "num_additional_zookeeper_nodes": 0, 
  "servers": [], 
  "zookeeper_ensemble": null } 
}

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 List Deployments method (below).

Delete Deployment

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

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

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

{
  "detail": "Not found."
}

List Deployments

This method lists the deployments of an account.

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

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

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...>

List Deployment Details

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

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

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

{
  "name": "SolrFromAPI",
  "uid": "ss571300",
  "application": "Solr",
  "application_version": "7.2.1",
  "tier": "Silver",
  "http_endpoint": "https://ss571300-westus-azure.searchstax.com/solr/",
  "status": "Running",
  "provision_state": "Done",
  "termination_lock": false,
  "plan_type": "DedicatedDeployment",
  "plan": "DC4",
  "region_id": "westus",
  "cloud_provider": "Microsoft Azure",
  "cloud_provider_id": "azure",
  "num_additional_app_nodes": 0,
  "deployment_type": "Dedicated Cluster",
  "num_nodes_default": 3,
  "num_additional_zookeeper_nodes": 0,
  "servers": [
    "ss571300-3",
    "ss571300-2",
    "ss571300-1"
  ],
  "zookeeper_ensemble": "ss571300-3-westus-azure.searchstax.com:2181,ss571300-2-westus-azure.searchstax.com:2181,ss571300-1-westus-azure.searchstax.com:2181",
  "tag": [],
  "specifications": {
    "disk_space": "34359738368",
    "jvm_heap_memory": "2147483648",
    "physical_memory": "4294967296"
  }
}

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

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

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." }

List Plans

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

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>"

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

List Deployment Usage

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

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

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

[
    {
        "SKU":  "Backup Run",
        "startDate":  "2019-02-01",
        "endDate":  "2019-02-01",
        "objectID":  11091,
        "usage":  1,
        "tagCollection":  [

                          ]
    },
    {
        "SKU":  "DN1",
        "startDate":  "2019-02-01",
        "endDate":  "2019-02-05",
        "objectID":  "ss401197",
        "usage":  5,
        "tagCollection":  [

                          ]
    },
    {
        "SKU":  "DC4",
        "startDate":  "2019-02-05",
        "endDate":  "2019-02-18",
        "objectID":  "ss634663",
        "usage":  14,
        "tagCollection":  [
                              "blue",
                              "red"
                          ]
    },
]

Usage is the number of billable days between startDate and endDate, inclusively.

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.

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

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

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."
    }
]

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

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

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",
                          "timestamp":  "2019-02-27T17:48:11.049Z",
                          "alert_id":  176,
                          "name":  "Idle System",
                          "condition":  "System Load Average = 0.04"
                      },
                      {
                          "status":  "open",
                          "timestamp":  "2019-02-27T17:55:11.771Z",
                          "alert_id":  177,
                          "name":  "Idle System",
                          "condition":  "System Load Average = 0.03"
                      }
                  ],
    "deployment":  "ss927085"
}

Alerts Read

This method lists the 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 cURL:

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

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

{
    "alerts":  [
                   {
                       "status":  "enabled",
                       "metric":  "system_cpu_usage",
                       "max_alerts":  3,
                       "threshold":  90.0,
                       "host":  "ss927085-1",
                       "delay_mins":  1,
                       "operator":  ">",
                       "id":  560,
                       "unit":  "percent",
                       "name":  "high cpu load",
                       "repeat_every":  5,
                       "email":  "bruce@searchstax.com"
                   }
               ],
    "deployment":  "ss927085"
}

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

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\"
}

The response is a JSON object containing a simple message.

{
    "message":  "Success!"
}

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

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\"
}

The response is a JSON object containing a simple message.

{
    "message":  "Enabled alert high cpu load",
    "success":  "true"
}

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

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

The response is a JSON object containing a simple message.

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

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

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

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

{
    "alerts":  [
                   {
                       "status":  "enabled",
                       "host":  "ss927085-1",
                       "name":  "Test Heartbeat",
                       "failures":  1,
                       "interval":  2,
                       "id":  16,
                       "max_alerts":  3,
                       "email":  "bruce@searchstax.com"
                   }
               ],
    "deployment":  "ss927085"
}

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

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\":  \"*\",
}

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

{
    "message":  "Success!"
}

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.

This method uses Token authentication.

There is no request body.

When invoked from cURL:

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

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

{
    "status":  "enabled",
    "host":  "ss475684-1",
    "name":  "Heartbeat from API",
    "failures":  1,
    "interval":  1,
    "id":  27,
    "max_alerts":  5,
    "email":  [ "bruce@searchstax.co" ]
}

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".

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

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\"
}

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

{
    "message":  "Disabled all heartbeat alerts for ss475684",
    "success":  "true"
}

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".

This method uses Token authentication.

There is no request body.

When invoked from cURL:

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

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.

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

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/zookeeper-config/?page=<n>" \
  --header "Authorization: APIkey <apikey>"

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

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

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 cURL, use the -F, --form <name=content> param to specify name and files. This enables uploading of binary files. To force the zip value 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/

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

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

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

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/zookeeper-config/<name>/" \
  --header "Authorization: APIkey <apikey>"

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

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

curl --request DELETE "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/zookeeper-config/<name>/" \
  --header "Authorization: APIkey <apikey>"

The response is a JSON document containing a confirmation message.

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

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

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"

The response is a zip file containing the configset files from Zookeeper. Note the -o "filename.zip" parameter in cURL. This captures the downloaded zip file and writes it to the current directory.

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

Create Auth Token

API Key Authentication

Create API Key

Associate API Key to Deployment

API Key Deployments

Disassociate API Key from Deployment

Deployment API Key

Revoke API Key

Solr Basic Auth

Enable Basic Auth

Disable Basic Auth

Add Solr User

Delete Solr User

Get Solr Users

Set Solr User Password

Set Solr User Role

Deployment

Create Deployment

Delete Deployment

List Deployments

List Deployment Details

Deployment Health

List Plans

List Deployment Usage

Tags

Create Tag

Delete Tag

List Tags for Deployment

Get Deployment by Tags

Alerts

Metrics

Incidents

Alerts Read

Alerts Create

Alerts Update

Alerts Delete

Alerts Heartbeat List

Alerts Heartbeat Create

Alerts Heartbeat Read

Alerts Heartbeat Update

Alerts Heartbeat Delete

Zookeeper

Zookeeper-Config List

Zookeeper-Config Create

Zookeeper-Config Read

Zookeeper-Config Delete

Zookeeper-Config Download

Questions?