The Bonsai API is currently in its Alpha release phase. It may not be feature-complete, and is subject to change without notice. If you have any questions about the roadmap of the API, please reach out to support.
The Clusters API provides a means of managing clusters on your account. This API supports the following actions:
All calls to the Clusters API must be authenticated with an active API token.
<span id="bonsai-cluster-object"></span>
The Bonsai API provides a standard format for Cluster objects. A Cluster object includes:
<table>
<thead>
<tr>
<th>Attribute</th><th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>slug</td><td>A string representing a unique, machine-readable name for the cluster. A cluster slug is based its name at creation, to which a random integer is concatenated.</td>
</tr>
<tr>
<td>name</td><td>A string representing the human-readable name of the cluster.</td>
</tr>
<tr>
<td>uri</td><td>A URI to get more information about this cluster.</td>
</tr>
<tr>
<td>plan</td><td>An Object with some information about the cluster's current subscription plan. This hash has two keys:
You can see more details about the plan by passing the slug to the Plans API.
</td>
</tr>
<tr>
<td>release</td><td>An Object with some information about the cluster's current release. This hash has five keys:
You can see more details about the release by passing the slug to the Releases API.
</td>
</tr>
<tr>
<td>space</td><td>An Object with some information about where the cluster is running. This has three keys:
You can see more details about the space by passing the path to the Spaces API.
</td>
</tr>
<tr>
<td>stats</td><td>An Object with a collection of statistics about the cluster. This hash has four keys:
This attribute should not be used for real-time monitoring! Stats are updated every 10-15 minutes. To monitor real-time metrics, monitor your cluster directly, via the Index Stats API.
</td>
</tr>
<tr>
<td>access</td><td>An Object containing information about connecting to the cluster. This hash has several keys:
</td>
</tr>
<tr>
<td>state</td><td>A String representing the current state of the cluster. This indicates what the cluster is doing at any given moment. There are 8 defined states:
</td>
</tr>
</tbody>
</table>
<span id="view-all-clusters"></span>
The Bonsai API provides a method to get a list of all active clusters on your account. An HTTP GET call is made to the <span class="inline-code"><pre><code>/clusters</code></pre></span> endpoint, and Bonsai will return a JSON list of Cluster objects. This API call will not return deprovisioned clusters. This call uses pagination, so you may need to make multiple requests to fetch all clusters.
<table>
<thead>
<tr>
<th>Param</th><th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>q</td><td>Optional. A query string for filtering matching clusters. This currently works on name</td>
</tr>
<tr>
<td>tenancy</td><td>Optional. A string which will constrain results to parent or child cluster. Valid values are: parent, child</td>
</tr>
<tr>
<td>location</td><td>Optional. A string representing the account, region, space, or cluster path where the cluster is located. You can get a list of available spaces with the Spaces API. Space path prefixes work here, so you can find all clusters in a given region for a given cloud.</td>
</tr>
</tbody>
</table>
An HTTP GET call is made to <span class="inline-code"><pre><code>/clusters</code></pre></span>.
Upon success, Bonsai responds with an HTTP 200: OK code, along with a JSON list representing the clusters on your account:
<div class="code-snippet-container">
<a fs-copyclip-element="click-2" href="#" class="btn w-button code-copy-button" title="Copy">
<img class="copy-image" src="https://global-uploads.webflow.com/63c81e4decde60c281417feb/6483934eeefb356710a1d2e9_icon-copy.svg" loading="lazy" alt="">
<img class="copied-image" src="https://assets-global.website-files.com/63c81e4decde60c281417feb/64839e207c2860eb9e6aa572_icon-copied.svg" loading="lazy" alt="">
</a>
<div class="code-snippet">
<pre><code fs-codehighlight-element="code" fs-copyclip-element="copy-this-2" class="hljs language-javascript">{
"pagination": {
"page_number": 1,
"page_size": 2,
"total_records": 2
},
"clusters": [
{
"slug": "first-testing-cluste-1234567890",
"name": "first_testing_cluster",
"uri": "https://api.bonsai.io/clusters/first-testing-cluste-1234567890",
"plan": {
"slug": "sandbox-aws-us-east-1",
"uri": "https://api.bonsai.io/plans/sandbox-aws-us-east-1"
},
"release": {
"version": "7.2.0",
"slug": "elasticsearch-7.2.0",
"package_name": "7.2.0",
"service_type": "elasticsearch",
"uri": "https://api.bonsai.io/releases/elasticsearch-7.2.0"
},
"space": {
"path": "omc/bonsai/us-east-1/common",
"region": "aws-us-east-1",
"uri": "https://api.bonsai.io/spaces/omc/bonsai/us-east-1/common"
},
"stats": {
"docs": 0,
"shards_used": 0,
"data_bytes_used": 0
},
"access": {
"host": "first-testing-cluste-1234567890.us-east-1.bonsaisearch.net",
"port": 443,
"scheme": "https"
},
"state": "PROVISIONED"
},
{
"slug": "second-testing-clust-1234567890",
"name": "second_testing_cluster",
"uri": "https://api.bonsai.io/clusters/second-testing-clust-1234567890",
"plan": {
"slug": "sandbox-aws-us-east-1",
"uri": "https://api.bonsai.io/plans/sandbox-aws-us-east-1"
},
"release": {
"version": "7.2.0",
"slug": "elasticsearch-7.2.0",
"package_name": "7.2.0",
"service_type": "elasticsearch",
"uri": "https://api.bonsai.io/releases/elasticsearch-7.2.0"
},
"space": {
"path": "omc/bonsai/us-east-1/common",
"region": "aws-us-east-1",
"uri": "https://api.bonsai.io/spaces/omc/bonsai/us-east-1/common"
},
"stats": {
"docs": 0,
"shards_used": 0,
"data_bytes_used": 0
},
"access": {
"host": "second-testing-clust-1234567890.us-east-1.bonsaisearch.net",
"port": 443,
"scheme": "https"
},
"state": "PROVISIONED"
}
]
}</code></pre>
</div>
</div>
<span id="view-single-cluster"></span>
The Bonsai API provides a method to retrieve information about a single cluster on your account.
No parameters are supported for this action.
An HTTP GET call is made to <span class="inline-code"><pre><code>/clusters/[:slug]</code></pre></span>.
Upon success, Bonsai will respond with an <span class="inline-code"><pre><code>HTTP 200: OK</code></pre></span> code, along with a JSON body representing the Cluster object:
<div class="code-snippet-container">
<a fs-copyclip-element="click-3" href="#" class="btn w-button code-copy-button" title="Copy">
<img class="copy-image" src="https://global-uploads.webflow.com/63c81e4decde60c281417feb/6483934eeefb356710a1d2e9_icon-copy.svg" loading="lazy" alt="">
<img class="copied-image" src="https://assets-global.website-files.com/63c81e4decde60c281417feb/64839e207c2860eb9e6aa572_icon-copied.svg" loading="lazy" alt="">
</a>
<div class="code-snippet">
<pre><code fs-codehighlight-element="code" fs-copyclip-element="copy-this-3" class="hljs language-javascript">{
"cluster": {
"slug": "second-testing-clust-1234567890",
"name": "second_testing_cluster",
"uri": "https://api.bonsai.io/clusters/second-testing-clust-1234567890",
"plan": {
"slug": "sandbox-aws-us-east-1",
"uri": "https://api.bonsai.io/plans/sandbox-aws-us-east-1"
},
"release": {
"version": "7.2.0",
"slug": "elasticsearch-7.2.0",
"package_name": "7.2.0",
"service_type": "elasticsearch",
"uri": "https://api.bonsai.io/releases/elasticsearch-7.2.0"
},
"space": {
"path": "omc/bonsai/us-east-1/common",
"region": "aws-us-east-1",
"uri": "https://api.bonsai.io/spaces/omc/bonsai/us-east-1/common"
},
"stats": {
"docs": 0,
"shards_used": 0,
"data_bytes_used": 0
},
"access": {
"host": "second-testing-clust-1234567890.us-east-1.bonsaisearch.net",
"port": 443,
"scheme": "https"
},
"state": "PROVISIONED"
}
}</code></pre>
</div>
</div>
<span id="create-new-cluster"></span>
The Bonsai API provides a method to create new clusters on your account. An HTTP POST call is made to the <span class="inline-code"><pre><code>/clusters</code></pre></span> endpoint, and Bonsai will create the cluster.
<table>
<thead>
<tr>
<th>Param</th><th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td><td>Required. A String representing the name for your new cluster.</td>
</tr>
<tr>
<td>plan</td><td>A String representing the slug of the new plan for your cluster. You can get a list of available plans via the Plans API.</td>
</tr>
<tr>
<td>space</td><td>A String representing the Space slug where the new cluster will be created. You can get a list of available spaces with the Spaces API.</td>
</tr>
<tr>
<td>release</td><td>A String representing the search service release to use. You can get a list of available versions with the Releases API.</td>
</tr>
</tbody>
</table>
An HTTP POST call is made to /clusters along with a JSON payload of the supported parameters.
Bonsai will respond with an <span class="inline-code"><pre><code>HTTP 202: Accepted</code></pre></span> code, along with a short message and details about the cluster that was created:
<div class="code-snippet-container">
<a fs-copyclip-element="click-4" href="#" class="btn w-button code-copy-button" title="Copy">
<img class="copy-image" src="https://global-uploads.webflow.com/63c81e4decde60c281417feb/6483934eeefb356710a1d2e9_icon-copy.svg" loading="lazy" alt="">
<img class="copied-image" src="https://assets-global.website-files.com/63c81e4decde60c281417feb/64839e207c2860eb9e6aa572_icon-copied.svg" loading="lazy" alt="">
</a>
<div class="code-snippet">
<pre><code fs-codehighlight-element="code" fs-copyclip-element="copy-this-4" class="hljs language-javascript">{
"message": "Your cluster is being provisioned.",
"monitor": "https://api.bonsai.io/clusters/test-5-x-3968320296",
"access": {
"user": "utji08pwu6",
"pass": "18v1fbey2y",
"host": "test-5-x-3968320296",
"port": 443,
"scheme": "https",
"url": "https://utji08pwu6:18v1fbey2y@test-5-x-3968320296.us-east-1.bonsaisearch.net:443"
},
"status": 202
}</code></pre>
</div>
</div>
An <span class="inline-code"><pre><code>HTTP 422: Unprocessable Entity</code></pre></span> error may arise if you are trying to create one too many Sandbox clusters on your account:
<div class="code-snippet-container">
<a fs-copyclip-element="click-5" href="#" class="btn w-button code-copy-button" title="Copy">
<img class="copy-image" src="https://global-uploads.webflow.com/63c81e4decde60c281417feb/6483934eeefb356710a1d2e9_icon-copy.svg" loading="lazy" alt="">
<img class="copied-image" src="https://assets-global.website-files.com/63c81e4decde60c281417feb/64839e207c2860eb9e6aa572_icon-copied.svg" loading="lazy" alt="">
</a>
<div class="code-snippet">
<pre><code fs-codehighlight-element="code" fs-copyclip-element="copy-this-5" class="hljs language-javascript">{
"errors": [
"The requested plan is not available for provisioning. Solution: Please use the plans endpoint for a list of available plans.",
"Your request could not be processed. "
],
"status":422
}</code></pre>
</div>
</div>
If you are not creating a Sandbox cluster, please refer to the API Error 422: Unprocessable Entity documentation.
<span id="update-cluster"></span>
The Bonsai API provides a method to update the name or plan of your cluster. An HTTP PUT call is made to the <span class="inline-code"><pre><code>/clusters</code></pre></span> endpoint, and Bonsai will update the cluster.
<table>
<thead>
<tr>
<th>Param</th><th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td><td>A String representing the new name for your cluster. Changing the cluster name will not change its URL.</td>
</tr>
<tr>
<td>plan</td><td>A String representing the slug of the new plan for your cluster. Updating the plan may trigger a data migration. You can get a list of available plans via the Plans API.</td>
</tr>
</tbody>
</table>
To make a change to an existing cluster, make an HTTP PUT call to <span class="inline-code"><pre><code>/clusters/[:slug]</code></pre></span> with a JSON body for one or more of the supported params.
Bonsai will respond with an <span class="inline-code"><pre><code>HTTP 202: Accepted</code></pre></span> code, along with short message:
<div class="code-snippet-container">
<a fs-copyclip-element="click-6" href="#" class="btn w-button code-copy-button" title="Copy">
<img class="copy-image" src="https://global-uploads.webflow.com/63c81e4decde60c281417feb/6483934eeefb356710a1d2e9_icon-copy.svg" loading="lazy" alt="">
<img class="copied-image" src="https://assets-global.website-files.com/63c81e4decde60c281417feb/64839e207c2860eb9e6aa572_icon-copied.svg" loading="lazy" alt="">
</a>
<div class="code-snippet">
<pre><code fs-codehighlight-element="code" fs-copyclip-element="copy-this-6" class="hljs language-javascript">{
"message": "Your cluster is being updated.",
"monitor": "https://api.bonsai.io/clusters/[:slug]",
"status": 202
}</code></pre>
</div>
</div>
<span id="destroy-cluster"></span>
The Bonsai API provides a method to delete a cluster from your account.
No parameters are supported for this action.
An HTTP DELETE call is made to the <span class="inline-code"><pre><code>/clusters/[:slug]</code></pre></span> endpoint.
Bonsai will respond with an HTTP 202: Accepted code, along with a short message:
<div class="code-snippet-container">
<a fs-copyclip-element="click-7" href="#" class="btn w-button code-copy-button" title="Copy">
<img class="copy-image" src="https://global-uploads.webflow.com/63c81e4decde60c281417feb/6483934eeefb356710a1d2e9_icon-copy.svg" loading="lazy" alt="">
<img class="copied-image" src="https://assets-global.website-files.com/63c81e4decde60c281417feb/64839e207c2860eb9e6aa572_icon-copied.svg" loading="lazy" alt="">
</a>
<div class="code-snippet">
<pre><code fs-codehighlight-element="code" fs-copyclip-element="copy-this-7" class="hljs language-javascript">{
"message": "Your cluster is being deprovisioned.",
"monitor": "https://api.bonsai.io/clusters/[:slug]",
"status": 202
}</code></pre>
</div>
</div>
