One of the most consistent pieces of feedback we received in early access was a version of the same complaint: "The designs are useful but getting them into our actual workflow requires too many manual steps." A researcher would run a design session, get back a ranked candidate list with prediction data, and then spend 20-30 minutes copy-pasting sequences into their ELN, formatting them for gene synthesis ordering, and cross-referencing prediction scores manually. That friction compounds when you are running multiple design campaigns in parallel.
This post walks through the current state of API integration: how to use the Python SDK to run design requests programmatically, how to sync results directly to Benchling, and how to export codon-optimized FASTA files formatted for direct upload to gene synthesis order systems. The goal is end-to-end from design brief to synthesis order without manual transcription steps.
The Python SDK: three objects you work with
The Fermvyne Python SDK (fermvyne-sdk, installable via pip) exposes three primary objects: DesignRequest, DesignResult, and VariantExport.
A DesignRequest encodes everything about your design problem: the reference sequence or EC number you are starting from, the target reaction parameters, the expression host, and any additional constraints like temperature tolerance range or cofactor preference. This is the structured form of the design brief that the generation model receives.
from fermvyne import DesignRequest, FermvyneClient
client = FermvyneClient(api_key="your-key")
request = DesignRequest(
reference_ec="1.1.1.1",
substrate_smiles="CC(O)CC", # 2-butanol
expression_host="ecoli_bl21",
tm_min=55.0,
candidates=20
)
result = client.submit(request)
# result.job_id — poll or await completionThe DesignResult object returned contains the ranked candidate list, per-variant prediction scores with confidence intervals, and the raw sequences. Results are also accessible via the web UI if you prefer to review visually before exporting.
Benchling sync: what gets written where
The Benchling integration writes each candidate variant as a DNA sequence entity in a folder you designate at setup time. Per-variant metadata — predicted Tm, solubility score, cofactor preference prediction, and the design request job ID as a back-reference — is written as custom entity fields. This means you can filter and sort candidate panels directly within Benchling using your existing ELN workflows.
Setup requires a Benchling API token with write access to your target project folder. The SDK handles the mapping between Fermvyne's internal entity schema and Benchling's entity API; you do not need to write the sync logic yourself.
from fermvyne.integrations import BenchlingSync
sync = BenchlingSync(
benchling_token="your-benchling-token",
folder_id="lib_abc123"
)
sync.push(result, codon_optimize_for="ecoli_k12")The codon_optimize_for parameter triggers Fermvyne's codon optimization step before export. Codon tables are available for E. coli K-12, E. coli BL21, S. cerevisiae BY4741, B. subtilis 168, and Pichia pastoris X-33 in the current SDK release. If your host is not on that list, you can supply a custom codon usage table as a JSON file.
FASTA export for gene synthesis ordering
For direct gene synthesis ordering without going through an ELN, the VariantExport object generates FASTA files formatted to match the input requirements of major gene synthesis providers. The naming convention in the FASTA headers follows the format that synthesis ordering systems expect for batch uploads, including the sequence length, any restriction site exclusion annotations you specified, and optional cloning overhang sequences.
from fermvyne import VariantExport
exporter = VariantExport(result)
# Export top 10 candidates, codon-optimized for E. coli BL21
# Exclude EcoRI, BamHI restriction sites
# Add attB1/attB2 Gateway cloning overhangs
exporter.to_fasta(
"candidates_batch1.fasta",
n_top=10,
codon_host="ecoli_bl21",
exclude_sites=["EcoRI", "BamHI"],
overhangs="gateway_attb"
)The resulting FASTA file is formatted for direct batch upload. The export step also generates a companion CSV with the prediction metadata for all exported variants, so you have a record linking each synthesis order sequence to its predicted properties without having to reconstruct that information later from the job results.
A practical walkthrough: 18 minutes from brief to order
To make this concrete: here is what the full workflow looks like for a team member who already has the SDK configured and Benchling sync enabled.
Minutes 0-3: Write and submit the DesignRequest. For a standard request to a well-studied enzyme family — an SDR or ketoreductase, for example — generation typically completes within 4-8 minutes on our current infrastructure. For more complex requests involving novel substrate classes or multi-constraint designs, allow 15-20 minutes.
Minutes 3-11: Generation runs server-side. During this time you can prepare the Benchling folder and check the synthesis order portal is ready for batch upload. No action required on your end.
Minutes 11-15: Review results. The ranked candidate list with prediction scores is available in the SDK object and in the web UI simultaneously. For a 20-candidate return set, reviewing the top 10 by composite score and checking for any flag-level confidence warnings takes 3-4 minutes with practice.
Minutes 15-18: Push to Benchling, generate the synthesis FASTA, review the restriction site exclusion report (occasionally a sequence needs a manual check if a critical restriction site was difficult to exclude without disrupting predicted activity). Submit the synthesis order.
We are not saying every design campaign moves this fast. Campaigns with novel substrates, unusual hosts, or multi-enzyme pathway co-design are more complex and take longer. We are saying that the overhead between "design is done" and "synthesis order is submitted" should not be measured in hours, and the current SDK workflow brings it down to under 20 minutes for standard cases.
What the API does not handle yet
Honest list of current gaps. Multi-round campaign management — tracking which variants from round one were tested, feeding results back as conditioning data for round two generation — is supported in the web UI but not yet fully implemented in the SDK. The API endpoint exists and is documented, but the round-two conditioning workflow requires a manual review step in the current release. We are working on a fully programmatic round management interface.
Direct integration with liquid handler scheduling systems (Hamilton VENUS, Tecan FluentControl) is on the roadmap but not yet available. You can export a plate layout CSV from the SDK that describes which variants go in which wells, but the handoff to the liquid handler protocol file is still manual. If this integration matters to your workflow, the Docs page has a specification of the intermediate format so you can write the bridge script for your specific platform while we build the native connector.
The SDK is under active development. If you hit a workflow gap that is blocking you, the fastest path is to reach out directly at [email protected] — we prioritize integration improvements based on what teams actually need, and a specific use case description is more actionable than a feature request in the abstract.