+++
title = "Cluster API Introduction"
weight = 75
updated = 2023-07-19
aliases = ["/docs/cluster-api-introduction.html", "/docs/bonsai-api/endpoints/cluster-api/"]

[extra]
nav_title = "Cluster API Introduction"
weight = 10
+++

The Clusters API provides a means of managing clusters on your account.

### Alpha Stage

{% admonition(title="Info") %}
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](mailto:support@bonsai.io).
{% end %}

The Clusters API provides a means of managing clusters on your account. This API supports the following actions:

- **View all** clusters in your account
- **View** a single cluster in your account
- **Create** a new cluster
- **Update** a cluster in your account
- **Destroy** a cluster in your account

All calls to the Clusters API must be [authenticated](@/docs/api/authentication/overview/index.md) with an active [API token](@/docs/account/api-tokens/index.md).

<span id="bonsai-cluster-object"></span>

## The Bonsai Cluster Object

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:

- **slug**. The unique, machine-readable name of the plan.
- **uri**. A URI to retrieve more information about this plan.

You can see more details about the plan by passing the slug to the [Plans API](@/docs/api/endpoints/plans-api/index.md).
</td>
</tr>
<tr>
<td>release</td><td>An Object with some information about the cluster's current release. This hash has five keys:

- **version.** The version of the release this cluster is running on.
- **slug.** The unique slug of the release.
- **package_name**. The package name of the release.
- **service_type**. The name of the search service.
- **uri.** A URI to retrieve more information about this plan.

You can see more details about the release by passing the slug to the [Releases API](@/docs/api/endpoints/releases-api/index.md).
</td>
</tr>
<tr>
<td>space</td><td>An Object with some information about where the cluster is running. This has three keys:

- **path.** The path to the space. This string maps to a geographic region or data center.
- **region.** The geographic region in which the cluster is running.
- **uri.** A URI with more information about the space

You can see more details about the space by passing the path to the [Spaces API](@/docs/api/endpoints/spaces-api/index.md).
</td>
</tr>
<tr>
<td>stats</td><td>An Object with a collection of statistics about the cluster. This hash has four keys:

- **docs.** The number of documents in the index.
- **shards_used.** The number of shards the cluster is using.
- **data_bytes_used.** Integer representing the number of bytes the cluster is using on disk.

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](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-stats.html).
</td>
</tr>
<tr>
<td>access</td><td>An Object containing information about connecting to the cluster. This hash has several keys:

- **host.** The host name of the cluster.
- **port.** The HTTP port the cluster is running on.
- **scheme.** The HTTP scheme needed to access the cluster (defaults to "https")

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

- **DEPROVISIONED.** The cluster has been destroyed.
- **DEPROVISIONING.** The cluster is in the process of being destroyed.
- **DISABLED.** The cluster has been disabled.
- **MAINTENANCE.** The cluster is in maintenance mode.
- **PROVISIONED.** The cluster has been created and is ready for use.
- **PROVISIONING.** The cluster is in the process of being created.
- **READONLY**. The cluster is in read only mode.
- **UPDATING PLAN.** The cluster's plan is being updated.

</td>
</tr>
</tbody>
</table>

<span id="view-all-clusters"></span>

## View all clusters

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 `/clusters` 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.

#### Supported Parameters (Query String Parameters)

<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](@/docs/api/endpoints/spaces-api/index.md). Space path prefixes work here, so you can find all clusters in a given region for a given cloud.</td>
</tr>
</tbody>
</table>

#### HTTP Request

An HTTP GET call is made to `/clusters`.

#### HTTP Response

Upon success, Bonsai responds with an HTTP 200: OK code, along with a JSON list representing the clusters on your account:

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

<span id="view-single-cluster"></span>

## View a single cluster

The Bonsai API provides a method to retrieve information about a single cluster on your account.

#### Supported Parameters

No parameters are supported for this action.

#### HTTP Request

An HTTP GET call is made to `/clusters/[:slug]`.

#### HTTP Response

Upon success, Bonsai will respond with an `HTTP 200: OK` code, along with a JSON body representing the Cluster object:

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

<span id="create-new-cluster"></span>

## Create a new cluster

The Bonsai API provides a method to create new clusters on your account. An HTTP POST call is made to the `/clusters` endpoint, and Bonsai will create the cluster.

#### Supported Parameters

<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](@/docs/api/endpoints/plans-api/index.md).</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](@/docs/api/endpoints/spaces-api/index.md).</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](@/docs/api/endpoints/releases-api/index.md).</td>
</tr>
</tbody>
</table>

#### HTTP Request

An HTTP POST call is made to /clusters along with a JSON payload of the supported parameters.

#### HTTP Response

Bonsai will respond with an `HTTP 202: Accepted` code, along with a short message and details about the cluster that was created:

```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
}
```

#### Error

An `HTTP 422: Unprocessable Entity` error may arise if you are trying to create one too many Sandbox clusters on your account:

```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
}
```

If you are not creating a Sandbox cluster, please refer to the [API Error 422: Unprocessable Entity](@/docs/api/errors/422-unprocessable-entity/index.md) documentation.

<span id="update-cluster"></span>

## Update a cluster

The Bonsai API provides a method to update the name or plan of your cluster. An HTTP PUT call is made to the `/clusters` endpoint, and Bonsai will update the cluster.

#### Supported Parameters

<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](@/docs/api/endpoints/plans-api/index.md).</td>
</tr>
</tbody>
</table>

#### HTTP Request

To make a change to an existing cluster, make an HTTP PUT call to `/clusters/[:slug]` with a JSON body for one or more of the supported params.

#### HTTP Response

Bonsai will respond with an `HTTP 202: Accepted` code, along with short message:

```javascript
{
  "message": "Your cluster is being updated.",
  "monitor": "https://api.bonsai.io/clusters/[:slug]",
  "status": 202
}
```

<span id="destroy-cluster"></span>

## Destroy a cluster

The Bonsai API provides a method to delete a cluster from your account.

#### Supported Parameters

No parameters are supported for this action.

#### HTTP Request

An HTTP DELETE call is made to the `/clusters/[:slug]` endpoint.

#### HTTP Response

Bonsai will respond with an HTTP 202: Accepted code, along with a short message:

```javascript
{
  "message": "Your cluster is being deprovisioned.",
  "monitor": "https://api.bonsai.io/clusters/[:slug]",
  "status": 202
}
```