benchling-integration

Files (6)

• SKILL.md
• api_endpoints.md · references/
• authentication.md · references/
• core_capabilities.md · references/
• eventbridge.md · references/
• sdk_reference.md · references/

SKILL.md (first lines)

# 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

```bash
uv pip install "benchling-sdk==1.25.0"
```

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

```python
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

```python
for page in benchling.containers.list(ancestor_storage_id="box_example"):
    for container in page:
        print(container.id, container.name, container.barcode)
```

`ancestor_storage_id` includes descendants. For immediate children only, inspect the
returned parent storage or use the documented storage-contents service.

### Export sequences for one schema

```python
import csv

with open("sequences.csv", "w", newline="", encoding="utf-8") as handle:
    writer = csv.DictWriter(handle, fieldnames=["id", "name", "bases", "length"])
    writer.writeheader()
    for page in benchling.dna_sequences.list(schema_id="ts_example"):
        for seq in page:
            writer.writerow({

From K-Dense-AI/scientific-agent-skills, MIT.

More from K-Dense-AI/scientific-agent-skills