← API reference
Structure prediction · Protein Design · Property prediction

Boltz-2 API

Predict a biomolecular complex and optional ligand affinity.

Builds the preferred Boltz YAML input and invokes the official boltz CLI. Runs single-sequence by default: no MSA server is contacted unless explicitly enabled.

Web form Documentation ↗ Home page ↗ Source code ↗
Submit POST /api/boltz2/

Queues a run and returns 202 with the job.

Schema GET /api/boltz2/

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

Runtime

Installed by setup_system.sh into its own uv environment; model weights download on first execution · Python app (uv) · Expensive (min or hours)

License

Permissive. MIT, covering the model weights as well as the 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
sequence default Sequence
list Chain list
molecules Molecules (JSON)
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 boltz2-demo Job name
sequence_molecules sequence string (JSON array) molecule_builder yes [{"type": "protein", "sequence": "MVTAYIAKQRQISFVKSHFSRQDILDLWIYHTQGYFP", "cyclic": false, … Molecules Add one box per chain: Protein, Ligand, DNA, or RNA. Ligands take a SMILES string or a CCD_ code (e.g. CCD_ATP). A modification applies a CCD residue code at a given position; "Cyclic" marks the chain cyclic. One of: protein, ligand, dna, rna. A JSON array, sent as a string. See molecule entries.
proteins list string textarea yes MVTAYIAKQRQISFVKSHFSRQDILDLWIYHTQGYFP Protein chains One protein chain sequence per line.
dnas list string textarea no — DNA chains (optional) One DNA chain sequence per line.
rnas list string textarea no — RNA chains (optional) One RNA chain sequence per line.
molecules molecules string textarea yes [{"type": "protein", "chain": "A", "sequence": "MVTAYIAKQRQISFVKSHFSRQDILDLWIYHTQGYFP"}] Molecules JSON list of {"type": "protein"|"dna"|"rna", "chain": "A", "sequence": "..."}.
yaml_spec yaml string textarea yes version: 1 sequences: - protein: id: A sequence: MVTAYIAKQRQISFVKSHFSRQDILDL … Design specification (YAML) A complete Boltz YAML input, used as-is (ligands, bonds, restraints, templates below are ignored for this task).
ligands list molecules yaml string textarea no — Ligands (optional) One ligand per line: a SMILES string, or CCD_<code> for a CCD component.
affinity boolean checkbox no true Predict affinity of the first ligand
cyclic list molecules yaml boolean checkbox no false Treat protein chains as cyclic
use_msa_server boolean checkbox no false Use the public MSA server Opt in to a network call to ColabFold's MMseqs2 server for better accuracy. Off by default keeps the run local (single-sequence mode).
use_potentials boolean checkbox no false Use inference-time potentials
recycling_steps number number no 3 Recycling steps minimum 1, maximum 20.
sampling_steps number number no 200 Diffusion sampling steps minimum 10, maximum 1000.
diffusion_samples number number no 1 Diffusion samples minimum 1, maximum 50.
step_scale number number no 0 Step scale (optional) Diffusion temperature; lower increases diversity. Leave at 0 for Boltz's own default (~1.5). minimum 0, maximum 5, step 0.01.
seed number number no 0 Random seed minimum 0, maximum 2147483647.
output_format string select no mmcif Output format One of: mmcif, pdb.
bonds string textarea no — Covalent bonds (optional) JSON list, e.g. [{"atom1Chain":"A","atom1Idx":32,"atom1Atom":"C","atom2Chain":"B","atom2Idx":1,"atom2Atom":"N"}].
pocket_restraints string textarea no — Pocket restraints (optional) JSON list, e.g. [{"binderChain":"A","pocketChain":"B","pocketContacts":"5 6 7","maxDistance":6,"force":false}].
contact_restraints string textarea no — Contact restraints (optional) JSON list, e.g. [{"chainA":"A","res_idxA":1,"chainB":"B","res_idxB":1,"max_distance_angstrom":5,"force":false}].
modifications list molecules yaml string textarea no — Residue modifications (optional) JSON list, e.g. [{"chain":"A","ptmPosition":15,"ptmResidue":"SEP"}].
template_cif string file no — Template structure (mmCIF, optional) Uploaded mmCIF file used to template the prediction. file types .cif,.mmcif.
template_chain_ids string text no — Template applies to chains (optional) Comma-separated chain letters from above; blank matches automatically.
template_ids string text no — Template chain IDs (optional) Comma-separated chain IDs inside the template mmCIF, aligned with the chains above.
template_threshold number number no 0 Template distance threshold, angstrom (optional) minimum 0, maximum 20, step 0.1.

Molecule entry keys

KeyMeaning
type Which of the field's molecule types this entry is.
sequence The residues, for a protein, dna, or rna entry.
ligand A SMILES string or a CCD_ code, for a ligand entry.
ion An ion code, for an ion entry.
cyclic Whether a polymer chain is cyclic. Tools that cannot model one reject it rather than ignoring it.
modifications Substitutions, as {"position": <1-indexed integer>, "residue": "<CCD code>"} objects.
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/boltz2/ \
  -H 'Content-Type: application/json' \
  -d '{
  "task": "sequence",
  "job_name": "boltz2-demo",
  "sequence_molecules": "[{\"type\": \"protein\", \"sequence\": \"MVTAYIAKQRQISFVKSHFSRQDILDLWIYHTQGYFP\", \"cyclic\": false, \"modifications\": []}]",
  "affinity": true,
  "use_msa_server": false,
  "use_potentials": false,
  "recycling_steps": 3,
  "sampling_steps": 200,
  "diffusion_samples": 1,
  "step_scale": 0,
  "seed": 0,
  "output_format": "mmcif",
  "bonds": "",
  "pocket_restraints": "",
  "contact_restraints": "",
  "template_cif": "",
  "template_chain_ids": "",
  "template_ids": "",
  "template_threshold": 0
}'

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.