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

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 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 Benchling SDK obeys Semantic Versioning, 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 to be notified of new releases.

Benchling MCP

The Benchling MCP obeys Semantic Versioning, 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: we recommend subscribing to the RSS version 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.

At what point can I update my code or queries to address a breaking change?

This varies by situation. Typically, you can migrate to the new functionality as soon as a change is communicated. In rare cases, a change is not backwards-compatible and a code change on our end might not land until after a deprecation period has ended.

The changelog entry will include all details necessary to migrate smoothly.

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?

To use an endpoint that's in beta, you need two things:

1. The beta feature needs to be enabled in your tenant (typically via a config flag change — contact your account team to request access).
2. Your API request needs to include the beta opt-in header (see the API reference for the required header name and value).