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

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

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:

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.

Tags

The SearchStax Provisioning API includes methods for adding tags to deployments, and for finding deployments by doing a tag search.

Create Tag

This method adds one or more tags to a deployment.

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

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:

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

When invoked from cURL:

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

The response is a list of JSON documents containing the deployment UID and the deployment's current set of tags.

[ { "deployment": "ssXXXXXX", "tags": [ "test", "demo" ] } ]

An invalid UID will throw a 404 - Not Found error.

Delete Tag

This method deletes one or more tags from a deployment.

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

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:

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

When invoked from cURL:

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

The response is a list of JSON documents identifying the deployment and its current set of tags:

[ { "deployment": "ssXXXXXX", "tags": [ "demo" ] } ] 

An invalid UID will throw a 404 - Not Found error.

List Tags for Deployment

This method list a deployment's current set of tags.

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

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

The response is a list of JSON documents identifying the deployment and its current set of tags:

[ { "deployment": "ssXXXXXX", "tags": [ "test", "demo" ] } ]

Get Deployment by Tags

This method retrieves all of the deployments that have a specific tag.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/tags/get-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:

{
    "tags":["test","demo"],
    "operator":"OR"
}
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"

When invoked from cURL:

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/tags/get-deployments/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data "{
    \"tags\":[\"test\",\"demo\"],
    \"operator\":\"OR\"
}"

The response is a list of JSON objects pairing tag matches with specific deployment UIDs.

[ { "tags": [ "demo" ], "deployment": "ssXXXXX1" }, 
  { "tags": [ "demo" ], "deployment": "ssXXXXX2" } ]

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.