> This page is for Developer Documentation.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.benchling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server.

# V3 Stability Guidelines

This guide provides an overview of the guarantees that Benchling makes for public developer interfaces and how breaking changes are communicated.

## Public API

Our v3 public API has two stability levels, `stable` and `beta`. As a general rule, these stability levels are aligned to the product's current state. A product or feature that is generally available will typically have a `stable` public API, while products and features in (open or closed) beta or Limited Availability expose `beta` endpoints.

Here is what to know about developing with stable and beta endpoints:

|                           | **stable**             | **beta**          |
| ------------------------- | ---------------------- | ----------------- |
| Breaking change frequency | Rare                   | Frequent          |
| Breaking change window    | 90 days\*              | N/A\*\*           |
| Recommended environments  | prod, test, dev, other | test and dev only |

Breaking changes to `stable` endpoints are rare. We only break stable interfaces when absolutely necessary. Breaking changes typically fall within one of these categories:

* Deprecation of legacy functionality
* Significant feature redesign
* Security vulnerability
* Bug fix

\* The standard notice period is 90 days. The only allowed exception is urgent security and bug fixes where waiting 90 days to release the change is not acceptable.

\*\* Beta endpoints may change at any time without notice.

For `beta` endpoints, we reserve the right to make breaking changes at any point without notice. `beta` endpoints leverage pre-GA products. The ability to iterate quickly is vital to making a new product stable and generally available quickly. We do not recommend using `beta` endpoints on production environments. We do encourage using and testing these APIs and giving feedback to the Benchling product team (in the [Benchling Community](https://community.benchling.com/) or via your account team).

## Events

Events (delivered over webhooks) are pinned to the most recent version of an object. For example, if object `A` is `stable`, its corresponding event is also `stable`; if object `B` is in `beta`, its corresponding event is also in `beta`.

The same breaking change guidelines apply.

## Benchling SDK

The [V3 Python SDK](/docs/getting-started-with-the-v3-sdk) obeys [Semantic Versioning](https://semver.org/), meaning that breaking changes will only be made when a new major version is released.

SDK releases happen frequently but not on a set schedule. When new endpoints or features are available, a new SDK version is released. Follow our [changelog](/docs/changelog.rss) to be notified of new releases.

## Benchling MCP

The Benchling MCP obeys [Semantic Versioning](https://semver.org/), meaning that breaking changes will only be made when a new major version is released.

Non-breaking updates (new tools, improved descriptions) do not require a new version.

## Frequently Asked Questions

### How will I be notified of breaking changes?

We aim to reach as many developers as possible when communicating breaking changes. We guarantee to always use these channels:

* [Changelog](/docs/changelog): we recommend subscribing to the [RSS version](/docs/changelog.rss) of the changelog. Out-of-the-box RSS feed integrations can be used to broadcast updates to internal Teams or Slack channels.
* Benchling Community: a place where we advertise Open Beta programs and collect feedback. Not typically used to communicate breaking changes but a place to learn about new features before they are generally available.

In some cases, you may hear directly from your account team if you have been identified as being impacted by a breaking change that is not (yet) more broadly communicated.

We monitor usage, provide migration guidelines, and work directly with customers who need help migrating off of breaking functionality.

All breaking changes are communicated with clear guidelines and timelines for migrating off of breaking functionality.

### What counts as a breaking change to the V3 REST API?

In general, this guidance applies to the following backward-incompatible changes:

* Removing or renaming an endpoint
* Removing or renaming a response field
* Widening the type of a response field (e.g. non-nullable -> nullable)
* Adding a new required field to a POST/PATCH request body or making an optional field required
* Narrowing the type of a request field

Note that we consider the following changes *not* to be breaking and expect third-party integrations to be resilient to them:

* Adding a field to a response
* Adding a new member to an enum
* Changing the text of an error message

### What does it mean if an endpoint, field, or event is marked as "deprecated"?

We use `deprecated` to indicate that we intend to stop supporting a specific feature in the near future. As a general rule, the Benchling Product team will work with impacted customers and decide (depending on the blast radius and complexity of the breaking change) how much time to provide to migrate off of deprecated functionality.

### What happens when a `beta` endpoint is promoted to `stable`?

Once an endpoint is promoted to `stable`, the `beta` tag is removed from the API reference and it will immediately become available to all users in the stable API.

### How can I use a `beta` endpoint?

Beta endpoints are open to everyone. Your API request needs to include the beta opt-in header, `EARLY-ACCESS: true`.