+++
title = "Plans API Introduction"
weight = 76
updated = 2023-07-07
aliases = ["/docs/plans-api-introduction.html", "/docs/bonsai-api/endpoints/plans-api/"]

[extra]
nav_title = "Plans API Introduction"
weight = 20
+++

The Plans API gives users the ability to explore the different cluster subscription plans available to their 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 Plans API gives users the ability to explore the different cluster subscription plans available to their account. This API supports the following actions:

- View all plans available for your account.
- View a single plan available for your account.

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

## The Bonsai Plan Object

The Bonsai API provides a standard format for Plan objects. A Plan object includes:

<table>
<thead>
<tr>
<th>Attribute</th><th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>slug</td><td>A String representing a machine-readable name for the plan. </td>
</tr>
<tr>
<td>name</td><td>A String representing the human-readable name of the plan.</td>
</tr>
<tr>
<td>price_in_cents</td><td>An Integer representing the plan price in cents.</td>
</tr>
<tr>
<td>billing_interval_in_months</td><td>An Integer representing the plan billing interval in months.</td>
</tr>
<tr>
<td>single_tenant</td><td>A Boolean indicating whether the plan is single-tenant or not. A value of <strong>false</strong> indicates the Cluster will share hardware with other Clusters. Single tenant environments can be reached via the public Internet. Additional documentation <a href="@/docs/platform/bonsai-architecture/index.md">here</a>.</td>
</tr>
<tr>
<td>private_network</td><td>A Boolean indicating whether the plan is on a publicly addressable network. Private plans provide environments that cannot be reached by the public Internet. A <a href="@/docs/heroku/private-spaces-and-vpc-peering/index.md">VPC connection</a> will be needed to communicate with a private cluster.</td>
</tr>
<tr>
<td>available_releases</td><td>An Array with a collection of search release slugs available for the plan. Additional information about a release can be retrieved from the <a href="@/docs/api/endpoints/releases-api/index.md">Releases API</a>.</td>
</tr>
<tr>
<td>available_spaces</td><td>An Array with a collection of Space paths available for the plan. Additional information about a space can be retrieved from the <a href="@/docs/api/endpoints/spaces-api/index.md">Spaces API</a>.</td>
</tr>
</tbody>
</table>

## View all plans

The Bonsai API provides a method to get a list of all plans available to your account. An HTTP GET call is made to the `/plans` endpoint, and Bonsai will return a JSON list of Plan objects.

#### Supported Parameters

No parameters are supported for this action.

#### HTTP Request

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

#### HTTP Response

Upon success, Bonsai responds with an `HTTP 200: OK` code, along with a JSON list representing the Plans available to your account:

```javascript
{
  "plans": [
     {
        "slug": "sandbox-aws-us-east-1",
        "name": "Sandbox",
        "price_in_cents": 0,
        "billing_interval_in_months": 1,
        "single_tenant": false,
        "private_network": false,
        "available_releases": [
            "7.2.0"
        ],
        "available_spaces": [
            "omc/bonsai-gcp/us-east4/common",
            "omc/bonsai/ap-northeast-1/common",
            "omc/bonsai/ap-southeast-2/common",
            "omc/bonsai/eu-central-1/common",
            "omc/bonsai/eu-west-1/common",
            "omc/bonsai/us-east-1/common",
            "omc/bonsai/us-west-2/common"
        ]
     },
     {
        "slug": "standard-sm",
        "name": "Standard Small",
        "price_in_cents": 5000,
        "billing_interval_in_months": 1,
        "single_tenant": false,
        "private_network": false,
        "available_releases": [
           "elasticsearch-5.6.16",
           "elasticsearch-6.8.3",
           "elasticsearch-7.2.0"
        ],
        "available_spaces": [
           "omc/bonsai/ap-northeast-1/common",
           "omc/bonsai/ap-southeast-2/common",
           "omc/bonsai/eu-central-1/common",
           "omc/bonsai/eu-west-1/common",
           "omc/bonsai/us-east-1/common",
           "omc/bonsai/us-west-2/common"
        ]
     }
   ]
  }
```

## View a single plan

The Bonsai API provides a method to retrieve information about a single Plan available to your account.

#### Supported Parameters

No parameters are supported for this action.

#### HTTP Request

An HTTP GET call is made to `/plans/[:plan-slug]`.

#### HTTP Response

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

```javascript
{
   "slug": "sandbox-aws-us-east-1",
   "name": "Sandbox",
   "price_in_cents": 0,
   "billing_interval_in_months": 1,
   "single_tenant": false,
   "private_network": false,
   "available_releases": [
      "elasticsearch-7.2.0"
   ],
   "available_spaces": [
      "omc/bonsai-gcp/us-east4/common",
      "omc/bonsai/ap-northeast-1/common",
      "omc/bonsai/ap-southeast-2/common",
      "omc/bonsai/eu-central-1/common",
      "omc/bonsai/eu-west-1/common",
      "omc/bonsai/us-east-1/common",
      "omc/bonsai/us-west-2/common"
   ]
}
```