+++
title = "Spaces API Introduction"
weight = 78
updated = 2023-07-07
aliases = ["/docs/spaces-api-introduction.html", "/docs/bonsai-api/endpoints/spaces-api/"]

[extra]
nav_title = "Spaces API Introduction"
weight = 40
+++

The Spaces API provides users a method to explore the server groups and geographic regions available to their account, where clusters may be provisioned.

### 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 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](@/docs/api/authentication/overview/index.md) with an active [API token](@/docs/account/api-tokens/index.md).

## The Bonsai Space Object

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

<table>
<thead>
<tr>
<th>Attribute</th><th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>path</td><td>A String representing a machine-readable name for the server group.</td>
</tr>
<tr>
<td>private_network</td><td>A Boolean indicating whether the space is isolated and inaccessible from the public Internet. A <a href="https://docs.bonsai.io/article/117-private-spaces-and-vpc-peering">VPC connection</a> will be needed to communicate with a private cluster.</td>
</tr>
<tr>
<td>cloud</td><td>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.

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

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

```javascript
{
  "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:

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