ProteinMPNN API

Design protein sequences for a supplied backbone structure.

Runs the official ProteinMPNN fixed-backbone sequence-design script on selected PDB chains.

Web form Source code ↗

Submit POST /api/proteinmpnn/

Queues a run and returns 202 with the job.

Schema GET /api/proteinmpnn/

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

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	`proteinmpnn-demo`	Job name
`pdb`	string file	yes	`HEADER PASTE A PROTEIN BACKBONE PDB HERE`	Backbone mmCIF or PDB file mmCIF is converted to legacy PDB before design; chain ids in it must be a single character. file types .pdb,.ent,.cif,.mmcif.
`chains`	string text	yes	`A`	Chains to design Comma- or space-separated PDB chain IDs.
`designed_residues`	string textarea	no	`—`	Designed residues (optional) Restrict design to specific residues instead of a whole chain: one line per chain, e.g. "B 26 27 28 29 30". Chains left out are designed in full; residues not listed for a named chain are held fixed.
`homo_oligomer`	boolean checkbox	no	`false`	Tie designed chains as a homo-oligomer Symmetric copies: ties the same position across all designed chains to the same amino acid.
`model_type`	string select	no	`proteinmpnn`	Model type SolubleMPNN is trained on soluble proteins only, for designs meant to express without a membrane or aggregation-prone context. One of: `proteinmpnn`, `solublempnn`.
`model_name`	string select	no	`v_48_020`	Model One of: `v_48_002`, `v_48_010`, `v_48_020`, `v_48_030`.
`num_sequences`	number number	no	`4`	Sequences minimum 1, maximum 1000.
`temperature`	number number	no	`0.1`	Sampling temperature minimum 0.01, maximum 1, step 0.01.
`backbone_noise`	number number	no	`0.0`	Noise level Gaussian noise added to backbone coordinates at inference, separate from the model checkpoint's own training noise (v_48_002/010/020/030). minimum 0, maximum 1, step 0.01.
`seed`	number number	no	`0`	Random seed minimum 0, maximum 2147483647.
`omit_amino_acids`	string text	no	`X`	Omit amino acids One-letter amino-acid codes that ProteinMPNN must not sample anywhere.
`bias_amino_acids`	string text	no	`—`	Amino-acid bias (optional) Global per-amino-acid sampling bias, e.g. "W:3.0,P:3.0,C:3.0,A:-3.0".
`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}, "C3": {"P": 10.0}}.
`omit_amino_acids_per_residue`	string textarea	no	`—`	Per-residue omitted amino acids (optional) JSON object keyed by chain+residue, e.g. {"A1": "CP", "A2": "CW"}.

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/proteinmpnn/ \
  -H 'Content-Type: application/json' \
  -d '{
  "job_name": "proteinmpnn-demo",
  "pdb": "HEADER    PASTE A PROTEIN BACKBONE PDB HERE",
  "chains": "A",
  "designed_residues": "",
  "homo_oligomer": false,
  "model_type": "proteinmpnn",
  "model_name": "v_48_020",
  "num_sequences": 4,
  "temperature": 0.1,
  "backbone_noise": 0.0,
  "seed": 0,
  "omit_amino_acids": "X",
  "bias_amino_acids": "",
  "bias_amino_acids_per_residue": "",
  "omit_amino_acids_per_residue": ""
}'

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.