/benchling-integration

name: benchling-integration
description: Benchling Python SDK and REST API integration for registry entities, inventory, ELN entries, workflows, Benchling Apps, and Data Warehouse queries. Use when automating lab data with benchling-sdk or the v2 API.
license: MIT
allowed-tools: Read Write Edit Bash
compatibility: Requires Python 3.9+, benchling-sdk 1.25.0, network access, a Benchling tenant with API access, and API key or OAuth app credentials.
metadata:
  version: "1.7"
  last-reviewed: "2026-09-30"
  skill-author: K-Dense Inc.
  openclaw:
    primaryEnv: BENCHLING_API_KEY
    envVars:
    - name: BENCHLING_TENANT_URL
      required: true
      description: Benchling tenant base URL.
    - name: BENCHLING_API_KEY
      required: false
      description: API key auth (alternative to OAuth).
    - name: BENCHLING_CLIENT_ID
      required: false
      description: OAuth app client id.
    - name: BENCHLING_CLIENT_SECRET
      required: false
      description: OAuth app client secret.
    - name: BENCHLING_PROD_TENANT_URL
      required: false
      description: Production tenant URL (multi-env setups).
    - name: BENCHLING_PROD_API_KEY
      required: false
      description: Production API key (multi-env setups).
    - name: BENCHLING_STAGING_TENANT_URL
      required: false
      description: Staging tenant URL (multi-env setups).
    - name: BENCHLING_STAGING_API_KEY
      required: false
      description: Staging API key (multi-env setups).

Benchling Integration

When to use

Use this skill for Benchling registry entities, sequence imports, inventory, ELN entries, workflow tasks, apps, event-driven integrations, and warehouse analytics.

**Reviewed 2026-09-30:** examples target the released **benchling-sdk 1.25.0** and its stable **v2** API models. The [current authentication guide](https://docs.benchling.com/docs/authentication) recommends V3 for new development, while the [V3 guide](https://docs.benchling.com/docs/v3-api-overview) still describes endpoint-specific early access. Confirm your tenant's V3 availability and stability before migrating; these v2 SDK examples must not be mechanically rewritten to V3.

SDK imports, model serialization, and request construction were checked locally against 1.25.0. Tenant-dependent examples are **illustrative**: no authenticated requests, mutations, AWS deployment, or warehouse connection were run.

Workflow

1. Identify the tenant, API version, identity, and permissions. Use OAuth app credentials for background integrations; use delegated authorization when acting as an individual user. See [authentication](references/authentication.md). 2. Read the relevant schema and resolve actual folder, registry, status, and dropdown IDs. Preserve sequence alphabet/topology and sample units. A valid Python model does not establish biological correctness or satisfaction of a tenant's required fields. 3. Read a small filtered page before writing. Use typed SDK methods and check their actual parameter names; not all services share the same CRUD naming convention. 4. Construct and serialize a representative payload. For imports, retain external IDs and returned Benchling IDs so a retry can reconcile a partial run without duplicates. 5. Perform the requested operation and read back the result. Check terminal async status; completed polling can still mean `FAILED`.

Setup and a read-only query

uv pip install "benchling-sdk==1.25.0"

import os
from benchling_sdk.benchling import Benchling
from benchling_sdk.auth.client_credentials_oauth2 import ClientCredentialsOAuth2

tenant_url = os.environ["BENCHLING_TENANT_URL"].rstrip("/")
benchling = Benchling(
    url=tenant_url,
    auth_method=ClientCredentialsOAuth2(
        client_id=os.environ["BENCHLING_CLIENT_ID"],
        client_secret=os.environ["BENCHLING_CLIENT_SECRET"],
        token_url=f"{tenant_url}/oauth/token",
    ),
)
for page in benchling.dna_sequences.list(page_size=10, name_includes="plasmid"):
    for sequence in page:
        print(sequence.id, sequence.name)
    break  # deliberate first-page connectivity/permission check

A successful empty page is a valid connectivity result. It does not imply access to all projects. There is no documented v2 `users/me` route or SDK `users.get_me()`.

Important SDK conventions

• Import `fields` from `benchling_sdk.helpers.serialization_helpers`. Its input is

`{"field_name": {"value": value}}`, including the inner `value` mapping.

• Use `dna_sequence_id` for DNA updates and `workflow_task_id` for workflow updates.

Workflow task creation requires a `workflow_task_group_id`.

• Entry methods are `create_entry`, `get_entry_by_id`, `list_entries`, and `update_entry`.
• `list()` usually returns pages; iterate twice to reach the objects. `estimated_count`

is a property that can raise `NotImplementedError`, not a method or guaranteed count.

• Moving a tube uses `ContainerUpdate(parent_storage_id=...)`. Material transfer is a

separate operation; it changes contents and quantities.

• Register on creation with `registry_id` plus **either** `entity_registry_id` (a human

registry identifier) **or** `naming_strategy`. Do not confuse those with the registry's ID.

Common use cases

Import FASTA sequences

Install Biopython separately (`uv pip install biopython`). This illustrative import creates unregistered linear DNA; choose topology and resolve collisions before running.

from Bio import SeqIO
from benchling_sdk.models import DnaSequenceCreate

for record in SeqIO.parse("sequences.fasta", "fasta"):
    payload = DnaSequenceCreate(
        name=record.id,
        bases=str(record.seq),
        is_circular=False,
        folder_id="lib_example",
    )
    created = benchling.dna_sequences.create(payload)
    print(record.id, created.id)  # persist this mapping for restart/reconciliation

Audit inventory under a location

for page in benchling.containers.list