Master Benchling Integration

A scientific computing skill for integrating with Benchling — the cloud platform for life sciences R&D. Master Benchling Integration helps you programmatically access the Benchling API to manage DNA/RNA/protein sequences, inventory, notebook entries, and workflows for laboratory information management.

When to Use This Skill

Choose Master Benchling Integration when:

• Accessing Benchling registry entities (DNA sequences, proteins, oligos) via API
• Automating inventory management and sample tracking
• Creating or updating electronic lab notebook (ELN) entries programmatically
• Building integrations between Benchling and analysis pipelines

Consider alternatives when:

• You need general bioinformatics tools without Benchling (use BioPython)
• You're doing sequence analysis locally (use BioPython or BLAST)
• You need LIMS without Benchling specifically (evaluate alternatives)

Quick Start

Copy
claude "Fetch all DNA sequences from my Benchling registry that match a specific schema"

Copy
import requests

# Benchling API configuration
BENCHLING_URL = "https://your-tenant.benchling.com"
API_KEY = "sk_..."  # From Benchling Settings > API Keys

headers = {
    "Authorization": f"Basic {API_KEY}",
    "Content-Type": "application/json"
}

# List DNA sequences in a registry
response = requests.get(
    f"{BENCHLING_URL}/api/v2/dna-sequences",
    headers=headers,
    params={
        "schemaId": "ts_xxxx",     # Filter by schema
        "pageSize": 50,
        "sort": "modifiedAt:desc"
    }
)

sequences = response.json()["dnaSequences"]
for seq in sequences:
    print(f"{seq['name']} | {seq['entityRegistryId']} | {len(seq['bases'])} bp")

Core Concepts

Benchling API Resources

Resource	Endpoint	Description
DNA Sequences	/api/v2/dna-sequences	Registered DNA constructs
AA Sequences	/api/v2/aa-sequences	Protein sequences
Oligos	/api/v2/oligos	Oligonucleotide primers
Containers	/api/v2/containers	Physical sample containers
Entries	/api/v2/entries	ELN notebook entries
Workflows	/api/v2/workflow-tasks	Workflow task management
Custom Entities	/api/v2/custom-entities	User-defined entity types

Registry Operations

Copy
# Create a new DNA sequence in the registry
new_sequence = {
    "name": "pUC19-GFP-insert",
    "bases": "ATGGTGAGCAAGGGCGAGGAGCTGTTC...",
    "isCircular": True,
    "schemaId": "ts_plasmid_schema",
    "registryId": "src_xxxx",
    "namingStrategy": "NEW_IDS",
    "fields": {
        "Antibiotic Resistance": {"value": "Ampicillin"},
        "Insert Size": {"value": 720}
    }
}

response = requests.post(
    f"{BENCHLING_URL}/api/v2/dna-sequences",
    headers=headers,
    json=new_sequence
)
created = response.json()
print(f"Created: {created['entityRegistryId']}")

# Bulk register entities
bulk_request = {
    "dnaSequenceIds": ["seq_xxx1", "seq_xxx2", "seq_xxx3"],
    "registryId": "src_xxxx",
    "namingStrategy": "NEW_IDS"
}
requests.post(
    f"{BENCHLING_URL}/api/v2/dna-sequences:bulk-register",
    headers=headers,
    json=bulk_request
)

Inventory Management

Copy
# Search containers by barcode
response = requests.get(
    f"{BENCHLING_URL}/api/v2/containers",
    headers=headers,
    params={"barcodes": "BC-001234"}
)
container = response.json()["containers"][0]
print(f"Location: {container['parentStorageId']}")
print(f"Contents: {len(container['contents'])} entities")

# Transfer contents between containers
transfer = {
    "transfers": [{
        "sourceContainerId": "con_source",
        "destinationContainerId": "con_dest",
        "sourceConcentration": {"value": 100, "units": "nM"},
        "transferVolume": {"value": 5, "units": "uL"}
    }]
}
requests.post(
    f"{BENCHLING_URL}/api/v2/transfers",
    headers=headers,
    json=transfer
)

Configuration

Parameter	Description	Default
tenant_url	Your Benchling tenant URL	Required
api_key	API key from Benchling settings	Required
registry_id	Default registry for operations	None
page_size	Results per API page	50
rate_limit	Requests per second	10

Best Practices

1. Use pagination for large result sets. Benchling API returns paginated results. Always check for nextToken in the response and loop until exhausted. Setting pageSize to 100 (max) reduces the number of requests needed.

2. Cache schema IDs and registry IDs. These identifiers rarely change but are needed in many API calls. Fetch them once at the start of your script and reuse them rather than looking them up for every request.

3. Use bulk endpoints for batch operations. When registering or updating multiple entities, use bulk endpoints (bulk-register, bulk-update) instead of individual calls. This is faster and less likely to hit rate limits.

4. Handle rate limiting gracefully. Benchling enforces API rate limits. Implement exponential backoff with retry logic: wait 1 second on first 429 response, then 2, 4, 8 seconds. Most Benchling SDKs handle this automatically.

5. Validate entity schemas before creation. Fetch the schema definition first to understand required fields, allowed values, and field types. Creating entities with missing required fields returns cryptic errors — validating upfront saves debugging time.

Common Issues

API returns 401 Unauthorized. Verify your API key hasn't expired and that it has the necessary permissions (read, write, admin) for the endpoint you're calling. API keys are scoped to specific permissions — a read-only key can't create entities.

Entity creation fails with schema validation error. Check that all required custom fields are included in the request body with correct types. Field names are case-sensitive and must match the schema definition exactly. Use the /api/v2/schemas endpoint to inspect required fields.

Pagination returns duplicate results. If entities are modified while you're paginating, results may shift. Use sort=createdAt:asc for stable pagination order, and deduplicate results by entity ID on the client side.