Structure prediction · Property prediction

Boltz-2 API

All-atom biomolecular structure and binding-affinity prediction.

Models complex structures and binding affinities, a critical component towards accurate molecular design. Boltz-2 is the first deep learning model to approach the accuracy of physics-based free-energy perturbation (FEP) methods, while running 1000x faster — making accurate in silico screening practical for early-stage drug discovery.

Web form Documentation ↗ Input parameters ↗ Examples ↗ Home page ↗ Paper ↗ Source code ↗ License ↗

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.

Input method

Set input_mode to choose how inputs are supplied. Only fields for the selected method are used.

parameters: Set parameters here
text: Enter YAML or JSON
upload: Upload YAML or JSON

Example presets

Send {"preset": "protein_msa_server"} to load an example and its bundled inputs. Add other request fields to override its settings. The schema includes all presets under tool.presets.

preset	Description
`protein_msa_server`	Official protein example, with the public MSA server enabled because the YAML does not provide an MSA. Source ↗
`protein_single_sequence`	Official protein example that explicitly disables MSA input; it runs without an MSA server. Source ↗
`protein_multimer`	Official two-chain protein-complex example, with missing MSAs generated by the public server. Source ↗
`cyclic_protein`	Official cyclic-protein example using Boltz's native cyclic flag. Source ↗
`protein_ligand_affinity`	Official protein–ligand example requesting Boltz-2's affinity property for the ligand. Source ↗

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 Names the output directory for this run. up to 80 characters.
`sequence_molecules`	string (JSON array) molecule_builder	yes	`[{"type": "protein", "id": "A", "sequence": "QLEDSEVEAVAKGLEEMYANGVTEDNFKNYVKNNFAQQEIS", " …`	Molecules Add one box per unique protein, ligand, DNA, or RNA entity. Set its native Boltz chain ID (or comma-separated IDs for identical copies), sequence or ligand, cyclic flag, and residue modifications. A protein's MSA may be left blank (generated by the MSA server when it is on, otherwise single-sequence), set to an absolute .a3m or .csv path, or set to empty for single-sequence mode. One of: `protein`, `ligand`, `dna`, `rna`. A JSON array, sent as a string. See molecule entries.
`constraints`	string textarea	no	`—`	Constraints (JSON, optional) Native Boltz constraints array. Supports bond, pocket, and contact entries using the chain IDs above. up to 500000 characters.
`templates`	string textarea	no	`—`	Templates (JSON, optional) Native Boltz templates array. Each entry may select a CIF/PDB, chain mapping, force flag, and threshold. up to 500000 characters.
`properties`	string textarea	no	`—`	Properties (JSON, optional) Native Boltz properties array, such as [{"affinity": {"binder": "B"}}]. up to 500000 characters.
`yaml_spec`	string textarea	yes	`version: 1 sequences: - protein: id: A sequence: QLEDSEVEAVAKGLEEMYANGVTEDNF …`	Boltz input (YAML) Complete native Boltz YAML. Define protein, DNA, RNA, and ligand entities under sequences; optional constraints, templates, and affinity properties use the same schema as the Boltz CLI. A protein without an msa key gets one from the MSA server; give msa a path to supply your own, or msa: empty for single-sequence mode. In this form: Bio Web writes this text to input.yaml and passes that file to boltz predict. up to 500000 characters.
`inputs_file`	string file	no	`—`	Boltz input file (YAML) The YAML file defining this prediction, in the same schema as the Boltz CLI takes. In this form: Choose a file. Its contents are read here and sent as the input document. file types .yaml,.yml,.json.
`use_msa_server`	boolean checkbox	no	`true`	Use the public MSA server Generate an MSA for every protein that has no MSA of its own, using the ColabFold MMseqs2 server below. This sends those protein sequences to that server. Proteins with an MSA path or msa: empty are left as they are. Turn off for private sequences or offline runs; each protein then needs a path or msa: empty.
`msa_server_url`	string text	no	`https://api.colabfold.com`	MSA server URL ColabFold-compatible MMseqs2 endpoint; used only when the MSA server is on. The public server asks for serial queries from a single IP, so host your own for large batches.
`use_potentials`	boolean checkbox	no	`false`	Use inference-time potentials Apply Boltz-2 inference-time potentials to improve physical plausibility.
`recycling_steps`	number number	no	`3`	Recycling steps Number of recycling steps. The Boltz CLI default is 3. minimum 1, maximum 20, step 1.
`sampling_steps`	number number	no	`200`	Structure sampling steps Diffusion steps used for structure prediction. The Boltz CLI default is 200. minimum 10, maximum 1000, step 1.
`diffusion_samples`	number number	no	`1`	Structure samples Independent diffusion samples generated for each input. minimum 1, maximum 50, step 1.
`step_scale`	number number	no	`1.5`	Structure step scale Diffusion temperature/step size. Boltz-2 defaults to 1.5 and recommends values between 1 and 2; lower values increase diversity. minimum 0, maximum 5, step 0.01.
`sampling_steps_affinity`	number number	no	`200`	Affinity sampling steps Sampling steps for the affinity head. Used only when the YAML requests an affinity property. minimum 1, maximum 1000, step 1.
`diffusion_samples_affinity`	number number	no	`5`	Affinity samples Diffusion samples for the affinity head. The Boltz CLI default is 5. minimum 1, maximum 50, step 1.
`affinity_mw_correction`	boolean checkbox	no	`false`	Apply affinity molecular-weight correction Enable Boltz's molecular-weight correction for the affinity value head.
`seed`	number number	no	`0`	Random seed Seed used by the Boltz random-number generator. minimum 0, maximum 4294967295, step 1.
`output_format`	string select	no	`mmcif`	Coordinate format Format of predicted coordinate files. One of: `mmcif`, `pdb`.

Molecule entry keys

Key	Meaning
`type`	Which of the field's molecule types this entry is.
`id`	A chain/entity ID, or a list of IDs for identical copies. Tools with configurable IDs expose this inside each molecule box. CatPred, whose boxes are not chains of one structure, uses it for the enzyme's sequence ID (its pdbpath, which must name exactly one sequence) and for a substrate's optional label.
`count`	The number of identical copies. Used by tools whose native schema represents copy count separately from IDs.
`sequence`	The residues, for a protein, dna, or rna entry.
`ligand`	A SMILES string or a CCD_ code, for a ligand entry. CatPred resolves no CCD codes and takes SMILES only.
`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": <integer>, "residue": "<CCD code>"} objects. Position indexing follows the tool: ESMFold2 uses zero-based positions; the other molecule-builder tools use one-based positions.
`msa`	A tool-native MSA for supported protein/RNA entities. Boltz-2: an absolute .a3m/.csv path, or empty for single-sequence; omit it to generate one with the MSA server. ESMFold2: an absolute .a3m path, a serialized MSA, or a {"sequences": [...]} object.
`paired_msa_path`	An OpenDDE or Protenix protein paired-MSA path.
`unpaired_msa_path`	An OpenDDE or Protenix protein or RNA unpaired-MSA path.
`templates_path`	An OpenDDE or Protenix protein template-hits path.

Example

A request that runs

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

curl -X POST https://athanortools.com/api/boltz2/ \
  -H 'Content-Type: application/json' \
  -d '{
  "input_mode": "parameters",
  "job_name": "boltz2-demo",
  "sequence_molecules": "[{\"type\": \"protein\", \"id\": \"A\", \"sequence\": \"QLEDSEVEAVAKGLEEMYANGVTEDNFKNYVKNNFAQQEIS\", \"cyclic\": false, \"modifications\": []}]",
  "constraints": "",
  "templates": "",
  "properties": "",
  "use_msa_server": true,
  "msa_server_url": "https://api.colabfold.com",
  "use_potentials": false,
  "recycling_steps": 3,
  "sampling_steps": 200,
  "diffusion_samples": 1,
  "step_scale": 1.5,
  "sampling_steps_affinity": 200,
  "diffusion_samples_affinity": 5,
  "affinity_mw_correction": false,
  "seed": 0,
  "output_format": "mmcif"
}'

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

status	Meaning
`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.
`cancelled`	Abandoned at the submitter's request; there is no result. A job cancelled before its turn never ran at all.

Errors

code	Meaning
`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 tool 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.