Index of every page on this site: llms.txt
All skills
k-dense-ai avatar

/benchling-integration

@ec59a29
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/k-dense-ai/scientific-agent-skills/benchling-integration

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencessdk_reference.md

≈3.1k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Benchling Python SDK Reference

Targets 1.25.0, the stable release verified on 2026-09-30. Python requirement: >=3.9,<4. Install with uv pip install "benchling-sdk==1.25.0". Examples assume an initialized benchling client from authentication. All IDs and schema fields are placeholders. Model serialization and request construction were tested offline; server behavior remains illustrative until checked in your tenant.

Source of truth: versioned SDK reference and the released benchling-sdk / benchling-api-client Python packages. The interaction guide explains the patterns; use installed signatures when guide snippets differ.

Schemas and fields

from benchling_sdk.helpers.serialization_helpers import fields

custom_fields = fields({
    "concentration": {"value": 100.0},
    "notes": {"value": "QC passed"},
})
schema = benchling.schemas.get_entity_schema_by_id("ts_example")

Use actual field names, numeric types, units, multiplicity, and dropdown option IDs from the schema. fields() is a serializer, not schema validation. A field named concentration may be a custom number; it is not the inventory contents concentration. Omitting a field preserves it on a partial update; {"value": None} explicitly clears it when allowed. Do not confuse fields with the free-text custom_fields property.

Registry entities

DNA: create, register, read, update, archive

from benchling_sdk.models import (
    DnaSequenceCreate, DnaSequenceUpdate, EntityArchiveReason, NamingStrategy,
)
from benchling_sdk.helpers.serialization_helpers import fields

payload = DnaSequenceCreate(
    name="Construct-001",
    bases="ATCGATCG",
    is_circular=True,
    folder_id="lib_example",
    schema_id="ts_example",
    registry_id="src_example",
    naming_strategy=NamingStrategy.NEW_IDS,
    fields=fields({"gene_name": {"value": "GFP"}}),
)
sequence = benchling.dna_sequences.create(payload)
print(sequence.id, sequence.entity_registry_id)
sequence = benchling.dna_sequences.get_by_id(sequence.id)
updated = benchling.dna_sequences.update(
    dna_sequence_id=sequence.id,
    dna_sequence=DnaSequenceUpdate(
        fields=fields({"gene_name": {"value": "mCherry"}}),
    ),
)

For an unregistered entity omit registry_id and the naming arguments. For an explicit human registry ID, replace naming_strategy with entity_registry_id="CONSTRUCT001". These are mutually exclusive. Required schema fields are enforced during registration. sequence.id is the API ID; sequence.entity_registry_id is the human registry ID.

Archival is a separate requested operation, with an iterable of IDs and an enum:

benchling.dna_sequences.archive(
    dna_sequence_ids=["seq_example"],
    reason=EntityArchiveReason.RETIRED,
)

RNA, proteins, and custom entities

from benchling_sdk.models import (
    RnaSequenceCreate, RnaSequenceUpdate, AaSequenceCreate,
    CustomEntityCreate, CustomEntityUpdate,
)

rna = benchling.rna_sequences.create(RnaSequenceCreate(
    name="gRNA-001", bases="AUCGAUCG", is_circular=False,
    folder_id="lib_example",
))
benchling.rna_sequences.update(
    rna_sequence_id=rna.id,
    rna_sequence=RnaSequenceUpdate(name="gRNA-001-validated"),
)
protein = benchling.aa_sequences.create(AaSequenceCreate(
    name="Peptide-001", amino_acids="MSKGEELFTGVVPIL",
    folder_id="lib_example",
))
cell_line = benchling.custom_entities.create(CustomEntityCreate(
    name="HEK293T-Clone5", schema_id="ts_cellline", folder_id="lib_example",
    fields=fields({"passage_number": {"value": 15}}),
))
benchling.custom_entities.update(
    entity_id=cell_line.id,
    entity=CustomEntityUpdate(fields=fields({"passage_number": {"value": 16}})),
)

Mixtures

IngredientWriteParams uses separate amount and units, with explicit nullable provenance fields. There is no IngredientCreate in this release.

from benchling_sdk.models import MixtureCreate, IngredientWriteParams, IngredientMeasurementUnits

ingredient = IngredientWriteParams(
    component_entity_id="bfi_component",
    amount="100", units=IngredientMeasurementUnits.MG,
    catalog_identifier=None, component_lot_container_id=None,
    component_lot_entity_id=None, component_lot_text=None, notes=None,
)
mixture = benchling.mixtures.create(MixtureCreate(
    name="Example formulation", schema_id="ts_mixture", folder_id="lib_example",
    ingredients=[ingredient],
))

Resolve ingredient identity/lot and measurement dimensions before transfer or formulation; serialization does not establish material balance or concentration correctness.

Inventory

Storage and physical movement

from benchling_sdk.models import ContainerCreate, ContainerUpdate, BoxCreate, LocationCreate

location = benchling.locations.create(LocationCreate(
    name="Freezer A - Shelf 2", schema_id="locsch_example",
    parent_storage_id="loc_freezer",
))
box = benchling.boxes.create(BoxCreate(
    name="Box 01", schema_id="boxsch_example", parent_storage_id=location.id,
))
container = benchling.containers.create(ContainerCreate(
    name="Sample 001", schema_id="consch_example", parent_storage_id=box.id,
))
moved = benchling.containers.update(
    container_id=container.id,
    container=ContainerUpdate(parent_storage_id="loc_destination"),
)
for page in benchling.containers.list(ancestor_storage_id=box.id):
    for item in page:
        print(item.id, item.name)

When placing a container into a box, resolve the supported box position identifier from the box contents/reference; don't guess coordinates or assume every box has free space.

Check out and in

from benchling_sdk.models import ContainersCheckout, ContainersCheckin

benchling.containers.checkout(ContainersCheckout(
    assignee_id="usr_example", container_ids=["con_example"], comment="At bench",
))
benchling.containers.checkin(ContainersCheckin(
    container_ids=["con_example"], comments="Returned",
))

Check-in does not take a location_id. Change physical storage separately if needed.

Plates and material transfer

from benchling_sdk.models import PlateCreate

plate = benchling.plates.create(PlateCreate(
    name="PCR plate", schema_id="pltsch_example", barcode="PLATE001",
))

PlateCreate.wells, when used, is a PlateCreateWells mapping of positions to well creation properties (for example barcodes), not a list of WellCreate entity assignments. Read back well/container IDs, then transfer contents with the container service.

from benchling_sdk.models import MultipleContainersTransfer, ContainerQuantity, ContainerQuantityUnits

transfer_task = benchling.containers.transfer_into_containers([
    MultipleContainersTransfer(
        source_container_id="con_source",
        destination_container_id="con_destination",
        transfer_quantity=ContainerQuantity(units=ContainerQuantityUnits.UL, value=5.0),
    ),
])
completion = transfer_task.wait_for_completion(max_wait_seconds=60)
if not completion.success:
    raise RuntimeError("Benchling material transfer failed; inspect completion.errors")

This calls POST /api/v2/transfers and returns a TaskHelper. Check completion.success and completion.errors before consuming completion.response. Single-destination transfer uses transfer_into_container(destination_container_id, ContainerTransfer(...)), with destination_contents; it is a different payload. Neither method moves a tube to a box.

Notebook

from benchling_sdk.models import EntryCreate, EntryUpdate

entry = benchling.entries.create_entry(EntryCreate(
    name="Cloning experiment", folder_id="lib_example",
))
entry = benchling.entries.get_entry_by_id(entry.id)
updated_entry = benchling.entries.update_entry(
    entry_id=entry.id, entry=EntryUpdate(name="Cloning experiment - reviewed"),
)
for page in benchling.entries.list_entries(project_id="src_project", page_size=10):
    for item in page:
        print(item.id, item.name)
    break

Use entry_template_id and initial_tables for supported template-based creation. EntryUpdate updates metadata/schema fields; it is not arbitrary rich-text editing. There is no benchling.entry_links service in 1.25.0. Use supported schema link fields or template/table mechanisms for the intended relationship. Discover actual template requirements with entries.get_entry_template_by_id and entries.list_entry_templates.

Workflow tasks versus async tasks

from benchling_sdk.models import WorkflowTaskCreate, WorkflowTaskUpdate

task = benchling.workflow_tasks.create(WorkflowTaskCreate(
    workflow_task_group_id="wtg_example", assignee_id="usr_example",
))
updated_task = benchling.workflow_tasks.update(
    workflow_task_id=task.id,
    workflow_task=WorkflowTaskUpdate(status_id="wts_complete"),
)
for page in benchling.workflow_tasks.list(
    workflow_task_group_ids=["wtg_example"], status_ids=["wts_pending"],
):
    for item in page:
        print(item.id)

Resolve status IDs from the workflow task schema. There is no workflow_id filter or name/schema_id constructor field on WorkflowTaskCreate in this SDK. The task group provides workflow context. Validate scientific completion before changing a status.

Async server jobs are a separate service and endpoint:

from benchling_sdk.models import AsyncTaskStatus
from benchling_sdk.errors import WaitForTaskExpiredError

try:
    finished = benchling.tasks.wait_for_task(
        task_id="task_example", interval_wait_seconds=2, max_wait_seconds=60,
    )
    if finished.status != AsyncTaskStatus.SUCCEEDED:
        raise RuntimeError(f"Benchling job ended with {finished.status}")
except WaitForTaskExpiredError:
    # The server job can continue after the local timeout. Save its ID for later polling.
    print("[FAIL] Polling deadline reached; inspect task_example before resubmission")

The default polling deadline is 600 seconds. wait_for_task returns on terminal failure as well as success; do not treat return alone as a successful operation.

Pagination, errors, and retries

sequences = benchling.dna_sequences.list(schema_id="ts_example", page_size=50)
try:
    total = sequences.estimated_count
except NotImplementedError:
    total = None
for page in sequences:
    for seq in page:
        print(seq.id, seq.name)

The iterator is consumable once; create another for another pass. Count access may fetch a page and counts are approximate. returning can omit model attributes; do not access an unrequested property as if it were a complete resource.

from benchling_sdk.errors import BenchlingError

try:
    sequence = benchling.dna_sequences.get_by_id("seq_example")
except BenchlingError as error:
    print(f"[FAIL] Benchling HTTP status {error.status_code}")
    raise

BenchlingError covers HTTP failures; transport and parsing errors can still surface separately. Avoid logging request headers or sensitive response bodies.

from benchling_sdk.helpers.retry_helpers import RetryStrategy

retry_strategy = RetryStrategy(max_tries=3, backoff_factor=1.0)

Pass this to Benchling(..., retry_strategy=retry_strategy). Default max_tries=5 counts total attempts; default retry codes are 429, 502, 503, and 504. Set retry_strategy=None to disable. Retrying a write after an ambiguous failure requires reconciliation; do not assume every create is idempotent.

Direct requests and model compatibility

For a documented endpoint not wrapped by a service, use its exact path and response shape. api.get_response returns a Response whose parsed value is a dictionary:

response = benchling.api.get_response(url="/api/v2/projects?pageSize=1")
projects = response.parsed["projects"]

get_modeled(url, target_type) and post_modeled(url, target_type, body=...) use SDK deserializable models. Use the endpoint's actual response model; a list envelope is not a single resource. Unknown enums/polymorphic responses are preserved where supported, but new values still need application handling; successful deserialization does not mean the integration understands their scientific meaning.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts27d4 checks · Risk SAFE
  • Gen Agent Trust Hub27d

    This skill provides a secure framework for integrating with the Benchling platform. It correctly handles authentication via environment variables, uses pinned versions for its dependencies, and restricts network activity to the official Benchling API and trusted academic sources. No malicious patterns or security risks were identified.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at ec59a29. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 2 months ago
All 1 allowed tools
Read Write Edit Bash
Other metadata
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)."
      }
    ]
  }
}

README badge

README badge for k-dense-ai/scientific-agent-skills/benchling-integration