SearchStax API - Tags


Overview

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

This page describes how to add and manage tags using API methods.

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

Account Owner, Admin, or Technical Contact

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

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

Contents:

Related Pages:

account > deployment > tags > create

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 Linux (Bash script):

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

When invoked from Windows (PowerShell script):

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

$body = @{
    tags='demo','test'
}

$body = $body | ConvertTo-Json

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

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

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

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

account > deployment > tags > delete

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 Linux (Bash script):

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

When invoked from Windows (PowerShell script):

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

$body = @{
    tags='test'
}

$body = $body | ConvertTo-Json

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

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

{
  "deployment": "ss123456",
  "tags": []
} 

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

account > deployment > tags > list

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 Linux (Bash script):

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

When invoked from Windows (PowerShell script):

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

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

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

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

account > deployment > tags > get_deployments

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 Linux (Bash script):

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

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"

$body = @{
    tags='demo','test'
    operator='OR'
}

$body = $body | ConvertTo-Json

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

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

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

Questions?

Do not hesitate to contact the SearchStax Support Desk.