Sequence prediction · Protein Design

LigandMPNN API

Design protein sequences with ligand-, solubility-, or membrane-aware models.

Runs the official LigandMPNN run.py, ProteinMPNN's successor CLI covering protein, ligand-aware, soluble-only, and membrane-topology model types behind a single interface.

Web form Source code ↗

Submit POST /api/ligandmpnn/

Queues a run and returns 202 with the job.

Schema GET /api/ligandmpnn/

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

Tasks

Pick a mode with `task`

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

task	Mode
`protein_mpnn` default	ProteinMPNN
`ligand_mpnn`	LigandMPNN
`soluble_mpnn`	SolubleMPNN
`per_residue_label_membrane_mpnn`	Membrane (per-residue)
`global_label_membrane_mpnn`	Membrane (global)

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	`ligandmpnn-demo`	Job name
`pdb`	string file	yes	`HEADER PASTE A PROTEIN (OR PROTEIN-LIGAND) PDB HERE`	Structure file types .pdb,.ent,.cif.
`chains_to_design`	string text	no	`—`	Chains to design (optional) Comma-separated chain IDs; blank designs every chain in the structure.
`batch_size`	number number	no	`1`	Batch size Sequences generated = batch_size x number_of_batches. minimum 1, maximum 1000.
`number_of_batches`	number number	no	`1`	Number of batches minimum 1, maximum 100.
`temperature`	number number	no	`0.1`	Sampling temperature minimum 0.01, maximum 2, step 0.01.
`seed`	number number	no	`0`	Random seed minimum 0, maximum 2147483647.
`omit_amino_acids`	string text	no	`—`	Omit amino acids (optional) One-letter amino-acid codes to never sample, e.g. "CX".
`bias_amino_acids`	string text	no	`—`	Amino-acid bias (optional) Global per-amino-acid sampling bias, e.g. "A:-1.0,P:2.3".
`bias_amino_acids_per_residue`	string textarea	no	`—`	Per-residue amino-acid bias (optional) JSON object keyed by chain+residue, e.g. {"C1": {"G": -0.3, "P": 10.8}}.
`omit_amino_acids_per_residue`	string textarea	no	`—`	Per-residue omitted amino acids (optional) JSON object keyed by chain+residue, e.g. {"A1": "ACDEFG"}.
`fixed_residues`	string text	no	`—`	Fixed residues (optional) Space-separated "ChainResnum", e.g. "C1 C2 C3"; these residues are held fixed.
`redesigned_residues`	string text	no	`—`	Redesigned residues (optional) Space-separated "ChainResnum", the inverse of fixed_residues: only these are redesigned.
`homo_oligomer`	boolean checkbox	no	`false`	Tie designed chains as a homo-oligomer Symmetric copies: ties equivalent positions across all designed chains to the same amino acid.
`ligand_mpnn_use_atom_context` ligand_mpnn	boolean checkbox	no	`true`	Use nearby ligand atoms as context
`ligand_mpnn_use_side_chain_context` ligand_mpnn	boolean checkbox	no	`false`	Use fixed residues' side chains as ligand context
`ligand_mpnn_cutoff_for_score` ligand_mpnn	number number	no	`8.0`	Ligand context cutoff, angstrom minimum 1, maximum 30, step 0.5.
`transmembrane_buried` per_residue_label_membrane_mpnn	string text	no	`—`	Buried transmembrane residues Space-separated "ChainResnum", e.g. "A1 A2 A3".
`transmembrane_interface` per_residue_label_membrane_mpnn	string text	no	`—`	Interface-facing transmembrane residues Space-separated "ChainResnum".
`global_transmembrane_label` global_label_membrane_mpnn	string select	no	`0`	Transmembrane protein One of: `0`, `1`.
`pack_side_chains`	boolean checkbox	no	`false`	Pack side chains onto designed backbones
`number_of_packs_per_design`	number number	no	`4`	Side-chain packs per design 0 uses a single fast pack instead of resampling. minimum 0, maximum 32.
`pack_with_ligand_context`	boolean checkbox	no	`true`	Pack side chains with ligand context
`repack_everything`	boolean checkbox	no	`false`	Repack fixed residues' side chains too Off keeps fixed residues' side chains exactly as given.

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/ligandmpnn/ \
  -H 'Content-Type: application/json' \
  -d '{
  "task": "protein_mpnn",
  "job_name": "ligandmpnn-demo",
  "pdb": "HEADER    PASTE A PROTEIN (OR PROTEIN-LIGAND) PDB HERE",
  "chains_to_design": "",
  "batch_size": 1,
  "number_of_batches": 1,
  "temperature": 0.1,
  "seed": 0,
  "omit_amino_acids": "",
  "bias_amino_acids": "",
  "bias_amino_acids_per_residue": "",
  "omit_amino_acids_per_residue": "",
  "fixed_residues": "",
  "redesigned_residues": "",
  "homo_oligomer": false,
  "pack_side_chains": false,
  "number_of_packs_per_design": 4,
  "pack_with_ligand_context": true,
  "repack_everything": 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

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.

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 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.