+++
title = "Legacy API Overview"
weight = 92
updated = 2026-10-13
aliases = ["/docs/introduction-to-the-api.html", "/docs/bonsai-api/overview/", "/docs/api/errors/402-payment-required/", "/docs/api-error-402-payment-required.html", "/docs/troubleshooting/api-errors/402-payment-required/"]

[extra]
nav_title = "Overview"
weight = 10
+++

Bonsai provides a REST API at https://api.bonsai.io for managing clusters, exploring plans, and checking out versions and available regions.

{{ legacy_api_notice() }}

This introduction to the Bonsai API includes the following sections:

- **Introduction**: What is the API and what is required to make it work?
- **Request Data**. Sending data to the API.
- **Response Data**. Receiving data from the API.
- **Error Handling**. What to expect if something fails.
- **API Access Limitations**. How often can you hit the API?
- **Breaking Changes**. How Bonsai handles changes to the API.
- **Questions, Problems, Feature Requests**. Providing feedback about the API.

## Introduction

Bonsai provides a REST API at [https://api.bonsai.io](https://api.bonsai.io/) for managing clusters, exploring plans, and checking out versions and available regions. This API allows customers to create, view, manage and destroy clusters via HTTP calls instead of through the dashboard. The API supports four endpoints:

- [**Clusters API**](@/docs/api/legacy/endpoints/cluster-api/index.md). Create, view, manage and destroy clusters on your account.
- [**Plans API.**](@/docs/api/legacy/endpoints/plans-api/index.md) View subscription plans available to your account.
- [**Spaces API**](@/docs/api/legacy/endpoints/spaces-api/index.md). View locations where your account may provision new clusters.
- [**Releases API.**](@/docs/api/legacy/endpoints/releases-api/index.md) View versions of Elasticsearch and OpenSearch available to your account.

To interact with the API, users must create an API Token. You can read more about creating those tokens [here](@/docs/account/api-tokens/index.md). An API token looks like `bonsai_<key>_<secret>`, and its [scopes](@/docs/account/api-tokens/index.md#scopes) decide which API calls it can make. The API supports [multiple ways of authenticating](@/docs/api/legacy/authentication/overview/index.md) requests with an API token. All calls to the API using an API token are logged for auditing purposes.

The API generally conforms to RESTful principals. Users interact with their clusters using standard HTTP verbs such as GET, PUT, POST, PATCH and DELETE. The Bonsai API accepts and returns JSON payloads. No other formats are supported at this time.

## Request Data

The Bonsai API accepts request bodies in JSON format only. A request body that is not valid JSON gets an [HTTP 400: Bad Request](@/docs/api/legacy/errors/400-bad-request/index.md) response, and nothing in the request is applied:

```json
{
  "errors": [
    "The request body does not appear to be valid JSON."
  ],
  "status": 400
}
```

Creating and updating a cluster need a body, so an empty body on those calls gets the same error.

Send a `Content-Type: application/json` header with every request that has a body. Creating and updating a cluster read the body as JSON whatever the header says, but [destroying a cluster](@/docs/api/legacy/endpoints/cluster-api/index.md#destroy-cluster) only reads the `name` in its body when the header is `application/json`.

The API ignores the `Accept` header. Every response is JSON, whatever the request asks for.

## Response Data

The Bonsai API responds with standard HTTP response codes. All HTTP message bodies will be in JSON format. The API documentation for the call will describe the response bodies that a client should expect.

## Error Handling

In the event that one or more errors are raised, the API will return a JSON response detailing the problem. The response will have a status code, and an array of error messages. For example:

```json
{
  "errors": [
    "Unauthorized access"
  ],
  "status": 401
}
```

Error codes for the API are documented in the [API Errors](@/docs/api/legacy/errors/_index.md) section.

## API Access Limitations

The Bonsai API limits any given token to 60 requests per minute, across all endpoints. Requests to create a cluster (`POST /clusters`) are further limited to 5 per minute per token. Making too many requests in a short amount of time will result in a temporary period of [HTTP 429](@/docs/api/legacy/errors/429-too-many-requests/index.md) responses, each with a `Retry-After` header giving the number of seconds to wait.

We are rolling these limits out gradually, so a request over a limit may still be served for now. Don't rely on that: build your clients to stay under the limits, and to wait for the `Retry-After` period before retrying a request that gets a 429.

Additionally, a request is refused if:

- Your API token is missing, wrong, revoked or expired ([HTTP 401](@/docs/api/legacy/errors/401-unauthorized/index.md)).
- Your API token doesn't have the scope the request needs ([HTTP 403](@/docs/api/legacy/errors/403-forbidden/index.md)).

## Breaking Changes

The Bonsai team considers the following changes to be backwards compatible, and can be made without advance notice:

- Adding new API endpoints
- Non-breaking changes to existing API endpoints:
- Adding new optional parameters
- Adding additional attributes to response bodies
- Adding new, optional features
- Adding support for new formats(such as XML)
- Adding support for additional authentication options

## Questions, Problems, Feature Requests

The Bonsai team is committed to providing the best, most-reliable platform for deploying and managing Elasticsearch and OpenSearch clusters. If you have a question, issue, or just want to submit a feature request, please reach out to our support team at [support@bonsai.io](mailto:support@bonsai.io).