Changelog

Overview

The Benchling v3 REST API is now generally available. Built on a single shared definition layer, v3 behaves consistently across the whole API, more than doubles endpoint coverage, and adds full write coverage across the Benchling Platform. We recommend that all new integrations build on v3 and that existing v2 integrations begin planning their migration.

The Beta Notebook Document APIs now support Results Tables as a first-class DocumentPart, along with new partsMutation operations for inserting rows and updating cells in Results Tables and Unstructured Tables.

For full details and tutorials on how to use the new Results Table APIs, read the Working with Tables API Guide →

Several updates have been made to the Beta Notebook Document APIs to improve the structure of the APIs to be more consistent. This update includes breaking changes to some endpoints and properties that may require attention.

This change removes two Beta v3 API endpoints for fetching Document Parts:

• GET /document-parts/{id}
• GET /document-parts/items

The same Document Part data can instead be returned by querying the following Entry-based endpoint instead:

• GET /entry/{entry_id}/parts/items

New Beta APIs for reading and editing Notebook entries have been added to V3. These APIs allow reading and writing the following document part types:

• Text
• Code block
• Sections
• Attachments
• Unstructured tables

For full details and tutorials on how to use the new Document APIs, read the new Documents API guide→

The V3 Search API now supports plate object types. You can include matrix-plate and well-plate in the objectTypes array on the Search request to return matrix plates and fixed (well) plates alongside other supported object types.

This change impacts the v3 REST APIs only (currently in open beta).

A summary of what shipped this week across the Benchling product.

The GET /benchling/enzyme/items endpoint now accepts id.anyOf, name.anyOf, and name.anyOf.caseSensitive query parameters, letting you filter Benchling’s global catalog of restriction enzymes by API ID or by name. These are the same filters already available on the v2 enzyme listing endpoint.

curl -u sk_YOUR_SECRET_KEY: \
  "https://$YOUR_DOMAIN.benchling.com/api/v3-beta/benchling/enzyme/items?name.anyOf=EcoRI,BamHI"

This change impacts the V3 REST APIs only (currently in open beta)

Fixed a bug where updating an existing dropdown option by specifying its id in the request body would return a 500 error. PATCH requests to update dropdown options now work as expected.

Developers are now able to select a webhookUrlRouting setting in the Developer Console. When using SUFFIXED (the default behavior), webhooks are delivered to the configured webhook url with a suffix. For example, for events webhooks, they are delivered to $WEBHOOK_URL/event. For canvas webhooks, they are delivered to $WEBHOOK_URL/canvas. For app lifecycle webhooks, they are delivered to $WEBHOOK_URL/lifecycle.

Overview

We are releasing a set of significant updates to the V3 REST API, including a unified API spec, new stability guidelines, and several new features. This release includes breaking changes. Please review the migration details below carefully.

Breaking Changes

Batch create and update endpoints are now available for every type. These endpoints allow you to write up to 25 objects in a single synchronous API request.

Returning and omit parameters are now available on all listing and get by id endpoints in the V3 REST API. You may specify them at request-time to change the top-level properties that are returned in the response object. Specify returning to include properties and specify omit to exclude properties. The two lists must be mutually exclusive.

This release pins benchling-api-client to 2.0.434 and includes a significant SDK-layer addition: rate limit headers are now accessible directly on the Benchling object after any API call. On the API side, notable changes include the addition of v3Id fields on AssayResult and AssayRun, a new base_molecule_link field type across all tiers, and HTML as a new export format option for notebook entries.

Homepage Canvas: Reset, Improved Initialization, and New Manifest Schema

We’ve made significant improvements to the Homepage Canvas to address two longstanding pain points: apps had no reliable way to know when to render the Canvas, and users had no way to recover when a Canvas became stuck or unresponsive.

This affects only the bulk ingest endpoint in v3 (currently in open beta)
Previously, bulk ingest async tasks would return as complete only if there were no errors in the ingestion.
The new behavior is that those tasks will now return as complete even if there are data-level errors in the ingestion. In order to understand if any items failed, developers will need to look at the error count value in the return data.

This change impacts the v3 REST APIs only (currently in open beta)

We removed the project.eq query filter from selected V3 REST API listing endpoints where project filtering is not supported.

The following listing endpoints no longer accept project.eq:

• GET /benchling/box/items
• GET /benchling/container/items
• GET /benchling/matrix-plate/items
• GET /benchling/plate/items
• GET /benchling/run/items
• GET /benchling/well-plate/items

Beginning on April 17, 2026, Assay Runs and Results will no longer be creatable from archived Run or Result schemas.

This release window covers four small, focused changes. Worklists are now a supported item type in search input UI blocks. A derivedFrom field on assay schemas is being deprecated. A new alpha endpoint enables programmatic rotation of OAuth2 client secrets for app definitions. The webhook envelope gains a required channel field to distinguish between the events and app_signals delivery channels.

This change impacts thev3 REST APIs only (currently in open beta)

The following endpoints were incorrectly present in both alpha and beta specs and have been removed:

• GET /benchling/request/items
• GET /benchling/request/{request_id}