← API reference
Binder design · Protein Design · Antibody design

BoltzGen API

Design a protein, peptide, nanobody, or antibody binder.

Builds a BoltzGen design specification YAML and runs the official boltzgen CLI end to end (design, inverse folding, and refolding).

Web form Home page ↗ Source code ↗
Submit POST /api/boltzgen/

Queues a run and returns 202 with the job.

Schema GET /api/boltzgen/

Returns this tool's metadata and the fields below, as JSON.

Runtime

Installed by setup_system.sh into its own uv environment; approximately 6 GB of model weights download separately · Python app (uv) · Expensive (min or hours)

License

Permissive. MIT, covering the weights and training data as well as the inference code: unrestricted academic and commercial use.

Tasks

Pick a mode with task

Fields belonging to another task are ignored, so send only the ones for the task you chose.

taskMode
protein default Protein binder
peptide Peptide
cyclotide Cyclotide
small_molecule Small-molecule binder
nanobody Nanobody
antibody Antibody
redesign Protein redesign
yaml YAML configuration
Request body

Fields

The same names the web form posts. See the field type table for what each kind means over HTTP.

Name Type Required Default Description
job_name string text no boltzgen-demo Job name
target_file protein string file yes — Target structure (PDB or mmCIF) Uploaded structure file for the binding target. file types .pdb,.cif,.ent,.mmcif.
target_chains protein string text no — Target chains (optional) Comma-separated chain IDs to include from the target file; blank includes all.
binding_site protein string text no — Binding site (optional) One "chain:residues" per line, e.g. "A:5..7,13"; BoltzGen residue ranges use "..".
not_binding_site protein string text no — Excluded site (optional) One "chain:residues" per line, residues the binder must not contact.
binder_chain_id protein string text no Z Binder chain ID
minimum_length protein number number no 60 Minimum binder length minimum 5, maximum 500.
maximum_length protein number number no 100 Maximum binder length minimum 5, maximum 500.
redesign_target_file redesign string file yes — Target structure (PDB or mmCIF) file types .pdb,.cif,.ent,.mmcif.
redesign_target_chains redesign string text no — Target chains (optional)
redesign_binding_site redesign string text no — Binding site (optional)
redesign_not_binding_site redesign string text no — Excluded site (optional)
redesign_binder_chain_id redesign string text no Z Binder chain ID
redesign_minimum_length redesign number number no 60 Minimum binder length minimum 5, maximum 500.
redesign_maximum_length redesign number number no 100 Maximum binder length minimum 5, maximum 500.
peptide_target_file peptide string file no — Target structure (PDB or mmCIF, optional) Leave blank to design a free peptide with no target. file types .pdb,.cif,.ent,.mmcif.
peptide_target_chains peptide string text no — Target chains (optional)
peptide_binding_site peptide string text no — Binding site (optional)
peptide_sequence peptide string text yes 10..20 Peptide sequence pattern A fixed sequence, a length range like "10..20", or a mix using BoltzGen's pattern syntax.
peptide_disulfide_bonds peptide string textarea no — Disulfide bonds (optional) JSON list, e.g. [{"position1": 2, "position2": 10}], 1-indexed into the peptide. Positions must land on a literal residue already written into the sequence pattern (e.g. a "C"), not inside a design-length run.
peptide_cyclic peptide boolean checkbox no false Cyclic backbone
peptide_chain_id peptide string text no Z Peptide chain ID
cyclotide_target_file cyclotide string file no — Target structure (PDB or mmCIF, optional) file types .pdb,.cif,.ent,.mmcif.
cyclotide_target_chains cyclotide string text no — Target chains (optional)
cyclotide_binding_site cyclotide string text no — Binding site (optional)
cyclotide_sequence cyclotide string text yes 3C8C6C5C3C1C2 Cyclotide sequence pattern BoltzGen sequence pattern mixing fixed residues and design-length runs.
cyclotide_disulfide_bonds cyclotide string textarea yes [{"position1": 4, "position2": 26}, {"position1": 13, "position2": 30}, {"position1": 20, … Disulfide bonds JSON list of 1-indexed {"position1", "position2"} pairs. Positions must land on a literal residue already written into the sequence pattern (e.g. one of its "C"s), not inside a design-length run.
cyclotide_chain_id cyclotide string text no Z Cyclotide chain ID
target_ligand_format small_molecule string select no smiles Target ligand format One of: smiles, ccd.
target_ligand small_molecule string text yes N[C@@H](Cc1ccc(O)cc1)C(=O)O Target ligand
small_molecule_minimum_length small_molecule number number no 100 Minimum binder length minimum 5, maximum 500.
small_molecule_maximum_length small_molecule number number no 150 Maximum binder length minimum 5, maximum 500.
small_molecule_target_chain_id small_molecule string text no L Target ligand chain ID
small_molecule_binder_chain_id small_molecule string text no Z Binder chain ID
nanobody_target_file nanobody string file yes — Target structure (PDB or mmCIF) file types .pdb,.cif,.ent,.mmcif.
nanobody_target_chains nanobody string text no — Target chains (optional)
nanobody_binding_site nanobody string text no — Binding site (optional)
nanobody_framework_file nanobody string file yes — Nanobody framework structure (PDB or mmCIF) A solved nanobody scaffold to graft new CDR loops onto. file types .pdb,.cif,.ent,.mmcif.
nanobody_framework_chain nanobody string text yes B Framework chain ID
nanobody_cdr_regions nanobody string text yes 26..34,52..59,98..118 CDR regions to redesign Residue ranges in the framework file, BoltzGen syntax (e.g. "26..34,52..59,98..118").
nanobody_cdr_exclude nanobody string text no — Framework residues to drop (optional) Residue ranges to strip from the template before redesign, e.g. to shorten a loop.
nanobody_cdr_insertions nanobody string textarea no — Variable-length insertions (optional) JSON list, e.g. [{"position": 26, "lengths": "1..5"}], inserted at a framework residue.
antibody_target_file antibody string file yes — Target structure (PDB or mmCIF) file types .pdb,.cif,.ent,.mmcif.
antibody_target_chains antibody string text no — Target chains (optional)
antibody_binding_site antibody string text no — Binding site (optional)
antibody_heavy_framework_file antibody string file yes — Heavy-chain framework structure file types .pdb,.cif,.ent,.mmcif.
antibody_heavy_framework_chain antibody string text yes B Heavy framework chain ID
antibody_heavy_cdr_regions antibody string text yes 26..32,52..57,99..110 Heavy-chain CDR regions
antibody_heavy_cdr_exclude antibody string text no — Heavy-chain residues to drop (optional)
antibody_heavy_cdr_insertions antibody string textarea no — Heavy-chain insertions (optional)
antibody_light_framework_file antibody string file yes — Light-chain framework structure file types .pdb,.cif,.ent,.mmcif.
antibody_light_framework_chain antibody string text yes A Light framework chain ID
antibody_light_cdr_regions antibody string text yes 24..34,50..56,89..97 Light-chain CDR regions
antibody_light_cdr_exclude antibody string text no — Light-chain residues to drop (optional)
antibody_light_cdr_insertions antibody string textarea no — Light-chain insertions (optional)
yaml_spec yaml string textarea yes entities: - protein: id: B sequence: 60..100 Design specification (YAML)
yaml_protocol yaml string select no protein-anything Protocol One of: antibody-anything, nanobody-anything, peptide-anything, protein-anything, protein-redesign, protein-small_molecule.
num_designs number number no 10 Intermediate designs minimum 1, maximum 10000.
budget number number no 1 Final design budget minimum 1, maximum 1000.
diffusion_batch_size number number no 0 Diffusion batch size (optional) Leave at 0 for BoltzGen's own default. minimum 0, maximum 1000.
omit_amino_acids string text no — Omit amino acids from inverse folding (optional) One-letter amino-acid codes to avoid when designing sequences.
skip_refolding boolean checkbox no false Skip refolding and confidence filtering Stops after design and inverse folding; faster, but skips BoltzGen's own quality filtering.
Example

A request that runs

These are the defaults, exactly as the web form would post them.

curl -X POST https://www.athanortools.com/api/boltzgen/ \
  -H 'Content-Type: application/json' \
  -d '{
  "task": "protein",
  "job_name": "boltzgen-demo",
  "target_file": "",
  "target_chains": "",
  "binding_site": "",
  "not_binding_site": "",
  "binder_chain_id": "Z",
  "minimum_length": 60,
  "maximum_length": 100,
  "num_designs": 10,
  "budget": 1,
  "diffusion_batch_size": 0,
  "omit_amino_acids": "",
  "skip_refolding": false
}'

The reply is 202 with a queued job; poll its status_url until status is succeeded or failed. See the quick start for the whole exchange.

Responses

What comes back

statusMeaning
queued Accepted, waiting for the jobs ahead of it. `position` counts how many those are.
running The tool is executing now.
succeeded Finished; `result` holds the tool's output and `license` the terms it came under.
failed Finished; `error` holds a code and a message.

Errors

codeMeaning
invalid_input The client supplied invalid or incomplete input.
tool_unavailable The requested third-party dependency is not available on this host.
execution_failed A configured third-party process exited unsuccessfully.
internal_error An adapter failed in a way it does not describe. The detail is in the server log, not the response.
not_found No job has that id. Finished jobs are dropped eventually.