+++
title = "Bonsai API v1"
weight = 84
updated = 2026-11-03

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

The Bonsai API v1 manages your account's clusters from code. With it you can:

- Create, rename and delete clusters, and change their plans.
- Create, read and revoke a cluster's credentials.
- Read a cluster's usage, request metrics and top search queries.
- List the plans, regions, private spaces and releases you can create clusters with.

Its base URL is:

```
https://api.bonsai.io/v1
```

Every request needs an [API token](@/docs/account/api-tokens/index.md), sent as a Bearer token:

```bash
curl https://api.bonsai.io/v1/account \
  -H "Authorization: Bearer bonsai_<key>_<secret>"
```

## Start here

- [Quickstart](@/docs/api/quickstart/index.md): create a cluster, connect to it and delete it, with `curl`.
- [Authentication](@/docs/api/authentication/index.md): tokens, and the scopes each operation needs.
- [Requests and responses](@/docs/api/requests-and-responses/index.md): bodies, IDs, pagination, and values that can grow.
- [Actions](@/docs/api/actions/index.md): how creating, deleting and changing a cluster's plan run, and how to follow them.
- [Retrying safely](@/docs/api/retrying-safely/index.md): idempotency keys.
- [Rate limits](@/docs/api/rate-limits/index.md): 60 requests a minute per token.
- [Errors](@/docs/api/errors/index.md): every error code, and what to do about it.
- [Versioning](@/docs/api/versioning/index.md): what can change within v1.
- [API reference](@/docs/api/reference/_index.md): every operation, parameter and field.

Moving an integration from the unversioned API? See [Moving from the legacy API](@/docs/api/migrating-from-legacy/index.md).

## The OpenAPI description

v1 is described by an OpenAPI 3.0 document, which the [API reference](@/docs/api/reference/_index.md) is built from. Use it to generate a client, or give it to a coding agent. None of these need a token:

- `https://api.bonsai.io/v1/openapi.json` and `https://api.bonsai.io/v1/openapi.yml`: the description.
- `https://api.bonsai.io/llms.txt`: a summary for language models.
- `https://api.bonsai.io/v1`: the API's version and these links.

The API also serves an interactive explorer of the same description at [api.bonsai.io/docs](https://api.bonsai.io/docs).

## Questions and feedback

If you have a question, a problem, or something you'd like the API to do, write to [support@bonsai.io](mailto:support@bonsai.io).
