> 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. # V2 Stability ## Are breaking changes made to the API, Warehouse, or Events? Generally no, but there are some exceptions. We do everything we can to keep our interfaces stable to keep from breaking our customer's integrations and apps that are built on top of them. If introducing a breaking change is absolutely necessary, we will give somewhere between **6-12 months** of lead time to allow customers to adapt/migrate when we are making a breaking change. 6 months is for small changes such as a single field rename, and up to 12 months for major changes such as a significant rework on an endpoint or table, or migration to a new endpoint or table. There are sometimes bugs that qualify as exceptional circumstances where we will make changes immediately, without providing a deprecation period, such as: * If a bug has been exploited to provide capability that is not intended to be supported, it will be patched and will not follow this process. * If a bug causes a significant performance issue, it will be patched and will not follow the process. Endpoints and tables tagged as `alpha` or `beta` do not fall under this guidance. See next section for details on these endpoints. ## What do `alpha` and `beta` mean in the API, Warehouse, and Events? When we are actively iterating on functionality in the API, Warehouse, and Events systems, we often want to expose new functionality before we finish iteration to get feedback from our users. When an endpoint, table, or event is in `alpha` or `beta`, it means we aren't entirely sure if this is how we want to reflect the data model or expose the functionality, and we want the flexibility to keep iterating. Expectations for each are listed below. ### Expectations for [`beta` endpoints](/docs/api/v2-beta) and tables Generally, we bring an endpoint, table, or event into `beta` because we know we want to have the functionality, but we still want the flexibility to change models. Breaking changes happen more than normal, but aren't frequent. **We give a 30 day deprecation period prior to removing the old behavior.** These endpoints, tables, or events are mostly locked in, but we might have to slightly change it due to a variety of reasons. We don't recommend using these for production use cases *unless* you are closely monitoring the use and ready to adapt on short notice if necessary. As an example, we've really only utilized this to change the name of endpoints, tables, and events or specific fields in the payload. We haven't previously made large architectural shifts while in `beta`. Warehouse `beta` tables are marked by having `$beta` in the table name. Example: `benchling.bnch$table$beta` ### Expectations for `alpha` endpoints and tables Endpoints, tables, and events in `alpha` are essentially ideas that we are debating. **We can make breaking changes to these at any time without warning, and can remove the functionality they provide entirely.** This is our space to give access temporarily for the purposes and gaining a better understanding of the use case, functionality, and format. You should not use `alpha` endpoints, tables, or events for anything other than testing and evaluation. We highly encourage you to provide feedback on them, as it is the most impactful time to do so! Warehouse `alpha` tables are marked by having `$alpha` in the table name. Example: `benchling.bnch$table$alpha` ## What about the Benchling SDK? The Benchling Python SDK obeys [Semantic Versioning](https://semver.org/), meaning that breaking changes will only be made when a new major version is released. Because it's possible to "pin" a specific SDK version, Benchling releases major versions of the SDK much more frequently than with the API & Events. Regardless, we do everything we can to keep the SDK's interfaces stable between versions. The Benchling SDK also includes support for some `alpha` and `beta` APIs. While Benchling makes no guarantees that `alpha` or `beta` APIs will be implemented in the SDK before their promotion to stable, any such services follow the same minimum breaking change warning as their corresponding `alpha` or `beta` API. Because SDK support tends to lag slightly behind API releases, breaking changes that are made to the API may not be reflected in the SDK until the next major version. ## What does "deprecated" mean? When we deprecate something in our developer platform, that means we are indicating that we plan to stop supporting the functionality (removing the field, parameter, event, or endpoint) in the future. **It does not mean we are stopping support for it immediately.** It allows us to indicate that developers should start planning how to adapt and that they should add the solution into their planned future work. If it's a stable endpoint or event, as in it's not in `beta` or `alpha`, that means developers should plan to do so in the next 6-12 months. If it's in `beta`, developers should plan to do so within 30 days. ![Benchling API reference showing the /oligos endpoints marked as deprecated](/_fern-files/_img/d7b3b6495737453e5e9b5f83704c34dbf66944db713e8889e016d4e0759db32e.webp) Prior to the end of the deprecation period, **the endpoint, event, or functionality is fully supported**. Nothing will suddenly change, except for `alpha` endpoints. When starting a new project, deprecated features should be avoided entirely. ## How will we notify of Breaking Changes? We'll notify of changes in some combination of a few channels: 1. We'll post them in our regular product release notes (reach out to [Benchling support](https://help.benchling.com/hc/en-us/requests/new) if you are not subscribed) as well as the [Benchling Developer Changelog](/docs/changelog) 2. We'll reach out to customers that are using the affected endpoint directly. Timelines quoted above will be included in the release notes and when we reach out directly.