ESMFold 2 API — Athanor Bio Tools

Submit POST /api/esmfold2/

Queues a run and returns 202 with the job.

Schema GET /api/esmfold2/

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": "carbonic_anhydrase_2cba"} 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
`carbonic_anhydrase_2cba`	Official ESMFold2 protein example (PDB 2CBA), using the released local API's 100-step example setting. Source ↗
`protein_dna_ligand_1mht`	Official local ESMFold2 example with protein HHAI, modified DNA, and CCD ligand SAH. 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	`esmfold2-demo`	Job name Used to name the predicted mmCIF file. up to 80 characters.
`sequence_molecules`	string (JSON array) molecule_builder	yes	`[{"type": "protein", "id": "A", "sequence": "MSHHWGYGKHNGPEHWHKDFPIAKGERQSPVDIDTHTAKYDPSLK …`	Molecules Add one box per unique ESMFold2 entity. Set its ID (or comma-separated IDs for identical copies), sequence or ligand, zero-indexed residue modifications, and optional protein/RNA MSA. An MSA is an absolute .a3m path on the compute node, a {"sequences": [...]} object whose first row is the query, or ESMFold2's serialized form; left blank, the chain folds from its sequence alone, which is ESMFold2's usual mode. Ligands may contain one or more comma-separated CCD_ codes. One of: `protein`, `ligand`, `dna`, `rna`. A JSON array, sent as a string. See molecule entries.
`pocket`	string textarea	no	`—`	Pocket conditioning (JSON, optional) Native ESMFold2 pocket object with binder_chain_id and contacts. up to 500000 characters.
`distogram_conditioning`	string textarea	no	`—`	Distogram conditioning (JSON, optional) Native ESMFold2 distogram_conditioning array with chain_id and JSON matrix values. up to 500000 characters.
`covalent_bonds`	string textarea	no	`—`	Covalent bonds (JSON, optional) Native ESMFold2 covalent_bonds array using chain_id, residue index, and atom index fields for each endpoint. up to 500000 characters.
`input_json`	string textarea	yes	`{ "sequences": [ { "type": "protein", "id": "A", "sequence": "MSHH …`	StructurePredictionInput (JSON) JSON representation of ESMFold2's StructurePredictionInput. Sequence entries use type protein, dna, rna, or ligand; polymers take id and sequence, while ligands take id plus either smiles or a ccd list. Native pocket, distogram, covalent-bond, modification, and serialized MSA fields are passed through. A protein or RNA msa may also be an absolute .a3m path, which is read with MSA.from_a3m. In this form: Modification positions are zero-indexed, exactly as in the official ESMFold2 Python dataclass. Use the JSON-safe shape produced by serialize_structure_prediction_input. up to 500000 characters.
`inputs_file`	string file	no	`—`	StructurePredictionInput file (JSON) The JSON file defining this prediction, in ESMFold2's own StructurePredictionInput format. In this form: Choose a file. Its contents are read here and sent as the input document. file types .json.
`num_loops`	number number	no	`20`	Recycling loops Recycling loops passed to ESMFold2InputBuilder.fold. The released API default is 20. minimum 1, maximum 64, step 1.
`num_sampling_steps`	number number	no	`200`	Diffusion sampling steps Diffusion sampling steps passed to ESMFold2InputBuilder.fold. The released API default is 200. minimum 2, maximum 1000, step 1.
`num_diffusion_samples`	number number	no	`1`	Diffusion samples Number of independently sampled structures. More than one produces one mmCIF per sample. minimum 1, maximum 16, step 1.
`seed`	number number	no	`0`	Random seed Seeds input preparation and diffusion sampling. minimum 0, maximum 4294967295, step 1.
`lm_dropout`	number number	no	`0.3`	Language-model dropout Inference-time LM embedding dropout. The released folding API defaults to 0.3; set 0 to disable it. minimum 0, maximum 1, step 0.01.
`chunk_size`	number number	no	`64`	Pair-operation chunk size Chunk size for memory-heavy pair operations. The released model defaults to 64; smaller values use less memory. Set 0 to disable chunking. minimum 0, maximum 512, step 1.
`device`	string select	no	`auto`	Device Auto selects CUDA when available and otherwise CPU. The published 6B model is intended for GPU inference. One of: `auto`, `cuda`, `cpu`.
`precision`	string select	no	`default`	Model precision Use the checkpoint's published dtype, or explicitly cast model weights to BF16 or FP32. One of: `default`, `bf16`, `fp32`.

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/esmfold2/ \
  -H 'Content-Type: application/json' \
  -d '{
  "input_mode": "parameters",
  "job_name": "esmfold2-demo",
  "sequence_molecules": "[{\"type\": \"protein\", \"id\": \"A\", \"sequence\": \"MSHHWGYGKHNGPEHWHKDFPIAKGERQSPVDIDTHTAKYDPSLK\", \"modifications\": []}]",
  "pocket": "",
  "distogram_conditioning": "",
  "covalent_bonds": "",
  "num_loops": 20,
  "num_sampling_steps": 200,
  "num_diffusion_samples": 1,
  "seed": 0,
  "lm_dropout": 0.3,
  "chunk_size": 64,
  "device": "auto",
  "precision": "default"
}'

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.