AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

benchling-integration

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.

Original source
K-Dense-AI
License
MIT
Pinned revision
5f2bc0341354fd5590aef76a533ada1e1e5b4e62

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read k-dense-ai--benchling-integration at revision 5f2bc0341354fd5590aef76a533ada1e1e5b4e62, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 6

references/sdk_reference.md

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.