Benchling API Client

Warnings

• breaking Major version updates (e.g., from 1.x to 2.x) in auto-generated clients frequently introduce breaking changes due to underlying API specification evolution. This can include altered method signatures, renamed parameters, or changes in data model structures.
  Fix: Refer to the official Benchling API documentation and the client's GitHub release notes for specific migration guides when upgrading across major versions.
• gotcha Many list endpoints in the Benchling API (e.g., `list_users`, `list_aa_sequences`) are paginated. To retrieve all results, you must iterate through pages using the `next_token` parameter from the response.
  Fix: Implement a loop that continuously calls the list method, passing the `next_token` from the previous response until no `next_token` is returned.
• gotcha The `host` configuration must be precise, including the `https://` prefix, your tenant name, and the `/api/v2` suffix (e.g., `https://my-org.benchling.com/api/v2`). Omitting parts of this URL is a common configuration error.
  Fix: Ensure your `host` string exactly matches the expected format for your Benchling tenant.
• gotcha API keys have specific scopes and permissions. If you encounter `403 Forbidden` errors, it likely indicates that your API key lacks the necessary permissions for the operation you are attempting. The client itself cannot bypass these API-level restrictions.
  Fix: Verify that your Benchling API key has the required read/write permissions for the specific resources and operations. Consult your Benchling tenant administrator or the Benchling API documentation on permissions.

Install

• pip install benchling-api-client Install stable version

Imports

• BenchlingClient

  from benchling_api_client import BenchlingClient

• Configuration

  from benchling_api_client import Configuration

• models

  from benchling_api_client import models

  Accesses generated data models like models.User or models.AaSequence.

Quickstart

This quickstart demonstrates how to initialize the Benchling API client using environment variables for credentials and make a simple call to list users. It highlights the required host format and accessing specific API endpoints via the client instance. The code includes a check for unset environment variables.

import os
from benchling_api_client import BenchlingClient, Configuration

# Benchling API keys are typically associated with a specific tenant.
# Set these environment variables: BENCHLING_TENANT_NAME, BENCHLING_API_KEY
# Example host: https://my-org.benchling.com/api/v2

benchling_tenant = os.environ.get('BENCHLING_TENANT_NAME', 'YOUR_TENANT_NAME')
benchling_api_key = os.environ.get('BENCHLING_API_KEY', 'YOUR_API_KEY')

if benchling_tenant == 'YOUR_TENANT_NAME' or benchling_api_key == 'YOUR_API_KEY':
    print("Please set BENCHLING_TENANT_NAME and BENCHLING_API_KEY environment variables.")
else:
    try:
        configuration = Configuration(
            host=f"https://{benchling_tenant}.benchling.com/api/v2",
            api_key={'api_key': benchling_api_key}
        )

        with BenchlingClient(configuration=configuration) as client:
            # The client provides direct access to various API namespaces (e.g., users, aa_sequences)
            users_api = client.users
            # List users, retrieving only the first page for demonstration
            response = users_api.list_users(page_size=1)
            
            if response.users:
                print(f"Found user: {response.users[0].handle} (ID: {response.users[0].id})")
            else:
                print("No users found or accessible with this API key.")

    except Exception as e:
        print(f"An error occurred: {e}")