Skip to main content

Introduction to the API

Rob Sears

Alpha Stage

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.

This introduction to the Bonsai API includes the following sections:

Introduction

Bonsai provides a REST API at 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. Create, view, manage and destroy clusters on your account.
  • Plans API. View subscription plans available to your account.
  • Spaces API. View locations where your account may provision new clusters.
  • Versions API. View versions of Elasticsearch available to your account.

To interact with the API, users must create an API Token. You can read more about creating those tokens here. An API token will have a key and a secret. The API supports multiple ways of authenticating requests with an API token. All calls to the API using an API token are logged for auditing purposes. Additional constraints on API tokens are in development.

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. Request bodies that are not in proper JSON will receive an HTTP 422: Unprocessable Entity response code, along with a JSON body containing messages about the problem.

A Content-Type: application/json HTTP header is preferred, but not required. Requests may also provide an Accept header, as either Accept: */* or Accept: application/json. Any other accept type will receive an HTTP 422 error.

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: 

{
  "errors": [
    "This request has failed authentication. Please read the docs or email us at support@bonsai.io."
  ],
  "status": 401
}

Error codes for the API are documented in the API Error Codes section.

API Access Limitations

The Bonsai API limits any given token to 60 requests per minute. Provision requests are limited to 5 per minute. Making too many requests in a short amount of time will result in a temporary period of HTTP 429 responses.
Additionally, access to the API may be blocked if:
  • Your Bonsai account is cancelled (HTTP 404).
  • Your Bonsai account is suspended due to non-payment (HTTP 402).
  • Your shared secret is revoked (HTTP 401).
  • If fraudulent or bot activity is suspected (HTTP 403).
  • Any violation of our Terms of Service (HTTP 403).

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 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.

Related articles