Skip to main content

Spaces API Introduction

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.

The Spaces API provides users a method to explore the server groups and geographic regions available to their account, where clusters may be provisioned. This API supports the following actions:
  • View all available spaces for your account
  • View a single space for your account
All calls to the Spaces API must be authenticated with an active API token.

The Bonsai Space Object

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

Attribute Description
path A String representing a machine-readable name for the server group.
private_network A Boolean indicating whether the space is isolated and inaccessible from the public Internet. A VPC connection will be needed to communicate with a private cluster.
cloud An Object containing details about the cloud provider and region attributes:

  • provider. A String representing a machine-readable name for the cloud provider in which this space is deployed.
  • region. A String representing a machine-readable name for the geographic region of the server group.

View all available spaces

The Bonsai API provides a method to get a list of all available spaces on your account. An HTTP GET call is made to the  /spaces endpoint, and Bonsai will return a JSON list of Space objects.
Supported Parameters

No parameters are supported for this action.

HTTP Request

An HTTP GET call is made to  /spaces.

HTTP Response

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

{
  "spaces": [
    {
      "path": "omc/bonsai/us-east-1/common",
      "private_network": false,
      "cloud": {
        "provider": "aws",
        "region": "aws-us-east-1"
      }
    },
    {
      "path": "omc/bonsai/eu-west-1/common",
      "private_network": false,
      "cloud": {
        "provider": "aws",
        "region": "aws-eu-west-1"
      }
    },
    {
      "path": "omc/bonsai/ap-southeast-2/common",
      "private_network": false,
      "cloud": {
        "provider": "aws",
        "region": "aws-ap-southeast-2"
      }
    }
  ]
}

View a single space

The Bonsai API provides a method to get information about a single space available to your account.
Supported Parameters

No parameters are supported for this action.

HTTP Request

An HTTP GET call is made to   /spaces/[:path].

HTTP Response

Upon success, Bonsai responds with an   HTTP 200: OK code, along with a JSON body representing the Space object: 

{
  "path": "omc/bonsai/us-east-1/common",
  "private_network": false,
  "cloud": {
    "provider": "aws",
    "region": "aws-us-east-1"
  }
}

Related articles