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

# Getting Started with the V2 SDK

A Python 3.7+ SDK for the Benchling platform designed to provide typed, fluent interactions with Benchling APIs.

> **Info**
>
> ### V2 SDK vs. V3 SDK
>
> This SDK (`benchling-sdk`) is generated from the V2 spec and calls V2 endpoints. For [V3](/docs/v3-api-overview), Benchling's recommended API for new development, use the separate [V3 Python SDK](/docs/getting-started-with-the-v3-sdk) (`benchling-v3-sdk-python`).
>
> Both versions accept the same token, so one integration can use both SDKs side by side while it moves to V3.

> **Info**
>
> ### Not Using Python?
>
> Our Python SDK leverages models generated from our [OpenAPI specification](https://benchling.com/api/v2/openapi.yaml). You can always generate a client in the language of your choice using the same specification through open source generators like this one at [OpenAPI Generator](https://openapi-generator.tech/). Please note that we do not test our OpenAPI specification with these generators though, and there might be unforeseen issues with the specific generator used.

## Why Use the SDK

Developers often create internal libraries (or leverage third-party ones) to handle interactions with Benchling's API, such as facilitating sleep & retry strategies after encountering a rate-limit error. The maintenance of these internal and/or third-party libraries can create significant overhead and make it harder to get started with our APIs.

We've helped alleviate much of this overhead with our Python SDK. At a high-level, our Python SDK provides a hassle-free library of Python classes and methods to handle the nuances of interacting with Benchling's API endpoints in a first-class manner.

Some notable benefits of leveraging Benchling's Python SDK include:

* *Get started faster* - An SDK package and an API key are all you need to start interacting with Benchling.
* *Work with Benchling Objects* - Resources are automatically constructed and deserialized into Python classes, freeing developers from JSON.
* *Fewer errors, More development* - Our Python SDK handles all of the nuances of connections, authentication, error handling, pagination, and retries in an off-the-shelf library.

Consider leveraging Benchling's Python SDK to shorten development timelines for all your software integrations using Benchling's APIs.

> **Info**
>
> ### An SDK, not an API
>
> This SDK is purely an *abstraction* on our [existing APIs](/docs/api/v2). It does not provide any interactions above and beyond those that are available by interacting with the APIs directly in another language, or through another package like `requests`.

## Getting Started

### Installation

#### Stable

Install the latest stable release of the Benchling SDK via *Poetry* (if applicable):

```bash
poetry add benchling-sdk
```

Or via *Pip*:

```bash
pip install benchling-sdk
```

#### Preview

Benchling also publishes preview builds, which are tagged "pre-release" in the benchling-sdk [release history](https://pypi.org/project/benchling-sdk/#history). Preview builds are pre-release, published frequently, and generally include features that are in active development. For the purposes of our [Stability Guidelines](/docs/stability) preview builds are considered alpha functionality, and are not intended for production use. We highly encourage you to provide feedback on them!

Install the latest preview release of the Benchling SDK by specifying the preview version; this can be done via Poetry (if applicable):

```bash
poetry add benchling-sdk --allow-prereleases
```

Or via *Pip*:

```bash
pip install benchling-sdk --pre
```

### Using the SDK

The Benchling SDK can use an API key or OAuth credentials for authentication. If you're using an API key, start by [obtaining a valid API key](https://help.benchling.com/hc/en-us/articles/9714802977805-Access-the-Benchling-Developer-Platform-Enterprise-) from your Benchling account and provide it to the SDK, along with the URL for your tenant.

Example:

```python
from benchling_sdk.benchling import Benchling
from benchling_sdk.auth.api_key_auth import ApiKeyAuth

benchling = Benchling(
    url="https://my.benchling.com",
    auth_method=ApiKeyAuth("api_key"),
)
```

If you're using OAuth credentials from an app, start by [obtaining a valid client ID and client secret](/docs/getting-started-benchling-apps#calling-the-api-as-an-app) from the app's settings page in Benchling. Then, provide the client ID and secret to the SDK, along with the URL for your tenant. You can also find [more examples using the SDK with an app](/docs/getting-started-benchling-apps#using-the-sdk).

Example:

```python
from benchling_sdk.benchling import Benchling
from benchling_sdk.auth.client_credentials_oauth2 import ClientCredentialsOAuth2

auth_method = ClientCredentialsOAuth2(
    client_id="{id_here}",
    client_secret="{secret_here}",
)
benchling = Benchling(
    url="https://{tenant_name}.benchling.com",
    auth_method=auth_method,
)
```

Now, with Benchling instantiated, make a sample call to list DNA Sequences:

```python
example_entities = benchling.dna_sequences.list()
for page in example_entities:
    for sequence in page:
        print(f"name: {sequence.name}\nid: {sequence.id}\n")
```

And you've successfully made a call to list DNA sequences from your tenant! To iterate through the list of DNA sequences you just retrieved, refer to the guidance on [iterating through pages](/docs/common-sdk-interactions-and-examples#iterating-through-pages).

## Next Steps

Check out [Common V2 SDK Interactions and Examples](/docs/common-sdk-interactions-and-examples) for code walkthroughs of other types of interactions users frequently do in our SDK, or check out [Browsing the SDK Reference](/docs/browsing-the-sdk-reference) to understand the full functionality that's exposed in the SDK!

## Support

If you have any issues with or questions about the SDK, please contact [Benchling support](https://help.benchling.com/hc/en-us/requests/new).