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

## SDK Version 1.11.0 Release

Version 1.11.0 of the Benchling SDK introduces a helper function verify for verifying webhooks, and deprecates the `verify_app_installation` in the `benchling_sdk.apps.helpers.webhook_helpers` module. When polling for Async tasks with `benchling.tasks.wait_for_task()`, the default `max_wait_seconds` has been raised from 30 seconds to 600 seconds. Other changes include new helper function for references in App Status, support for Python 3.12, and a bug fix in OAuthClientCredentials.

### What’s Changing?

#### Added

* Added `verify()` function in `benchling_sdk.apps.helpers.webhook_helpers` for verifying webhooks received from Benchling, wich replaces the now deprecated `verify_app_installation`. This uses the new URL [https://apps.benchling.com/api/v1/apps/\{app\_definition\_id}/jwks](https://apps.benchling.com/api/v1/apps/%7Bapp_definition_id%7D/jwks) for retrieving JWKs for verifying webhook signatures. See [Webhook Security](/docs/webhook-verification) for more info on webhook verification. This function replaces `verify_app_installation` for Global Apps; check out the [Global Apps FAQ](/docs/global-apps-faq) for more details.
* Added a new `ref_by_id(id: str)` function to the `benchling_sdk.apps.status.helpers` module. This enables referencing a Benchling object in an App Status message using just the object’s ID.
* Verified support for Python 3.12.

#### Changed

* Increased default wait time (`max_wait_seconds`) when using `benchling.tasks.wait_for_task()` to 600 seconds from 30 seconds.
  * Previously, tasks that exceed 30 seconds would cause a WaitForTaskExpiredError exception to be raised. Now, the `wait_for_task()` function will wait for up to 10 minutes before raising the exception. This reflects the time the SDK will poll Benchling to check if a task was completed, but does not affect the task’s actual completion status in Benchling.
    * **Note**: This might cause an increase in infrastructure timeouts in time-constrained environments like serverless functions (e.g. AWS Lambda)
  * The default wait time can be  can be overwritten, for example: wait\_for\_task(max\_wait\_seconds=custom\_value). Code that already sets max\_wait\_seconds instead of using the default is unaffected by this change.

#### Fixed

* Fixed a bug in OAuthClientCredentials where a JSONDecodeError would sometimes be raised when an HTTP error status code was returned. This will now log a debug message and raise BenchlingError.

#### Deprecated

* `benchling_sdk.apps.helpers.webhook_helpers.verify_app_installation` is now deprecated in favor of `benchling_sdk.apps.helpers.webhook_helpers.verify`

### When is this happening?

Version 1.11.0 of the Benchling SDK is now live! Find the SDK in [PyPI](https://pypi.org/project/benchling-sdk/1.11.0/).

## Entity upsert endpoints promoted to stable

A number of `upsert` endpoints are being promoted from `v2-beta` to the `v2` stable API. The new `v2` stable endpoints are now live; the corresponding `v2-beta` endpoints are now deprecated, and will be fully sunset at a later date.

### What’s changing?

A collection of endpoints that support an `upsert` operation are being promoted to the `v2` stable API. When provided with a list of objects that includes a Registry ID, these `upsert` endpoints either update an existing entity (if an entity with that Registry ID already exists) or create a new entity (if an entity with that Registry ID not does already exist). You can also use Registry IDs in schema field values to link to entities being created in the same upsert request.

The following endpoints have been promoted to `v2` stable and marked deprecated in `v2-beta`.

* `PATCH /dna-sequences/{entity_registry_id}:upsert`
* `PATCH /dna-oligos/{entity_registry_id}:upsert`
* `PATCH /rna-sequences/{entity_registry_id}:upsert`
* `PATCH /rna-oligos/{entity_registry_id}:upsert`
* `PATCH /aa-sequences/{entity_registry_id}:upsert`
* `PATCH /custom-entities/{entity_registry_id}:upsert`
* `PATCH /molecules/{entity_registry_id}:upsert`
* `POST /entities:bulk-upsert`
* `POST /dna-sequences:bulk-upsert`
* `POST /dna-oligos:bulk-upsert`
* `POST /rna-sequences:bulk-upsert`
* `POST /rna-oligos:bulk-upsert`
* `POST /aa-sequences:bulk-upsert`
* `POST /custom-entities:bulk-upsert`
* `POST /molecules:bulk-upsert`

### When is this happening?

The new `v2` stable `upsert` endpoints are now live! The corresponding `v2-beta` endpoints are now deprecated, and will be fully sunset at a later date. If you are currently using any `v2-beta` `upsert` endpoints, please migrate to the corresponding `v2` stable versions.