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

[extra]
nav_title = "Versioning"
weight = 45
+++

The version is in the path: `https://api.bonsai.io/v1`. Within v1, changes are only additive.

## What can change within v1

We can, without notice:

- Add operations, and optional parameters or body fields.
- Add fields to responses.
- Add values to open sets: cluster states, Action types and states, credential access types, and error codes.

So build your client to ignore fields it doesn't know, and to handle a state, type or code it doesn't know. The [API reference](@/docs/api/reference/_index.md) marks each open set. See [Values that can grow](@/docs/api/requests-and-responses/index.md#values-that-can-grow).

## Breaking changes

A change that would break a client goes into a new version, `/v2`.

If we ever retire something in v1, its responses will carry `Deprecation` and `Sunset` headers ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745) and [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) first, saying when it goes.

## The legacy API

The [legacy API](@/docs/api/legacy/_index.md), at `https://api.bonsai.io` without a version in the path, keeps working and is still supported, but gets no new features. [Moving from the legacy API](@/docs/api/migrating-from-legacy/index.md) maps each legacy call to its v1 equivalent.

## Changes

- **v1**: first release. Clusters, Actions, credentials, usage, metrics and top queries, and the plans, regions, spaces and releases to create clusters with.