Designs¶

POST /v1/designs designs de novo proteins against a target. Three engines share the endpoint: BoltzGen takes a protein, small-molecule, DNA or RNA target and returns designs ranked by predicted confidence; RFdiffusion3 takes a pasted structure plus a contig and returns them unranked; PXDesign takes a pasted structure plus the target chains and returns binder backbones with no sequence at all. All three return a job to poll, exactly like a prediction. Every example sends your key from $JAPANFOLD_API_KEY (see Authentication).

The protocol implies the model. You may pass model explicitly (boltzgen, rfd3 or pxdesign), but it has to match the protocol's model; a mismatch is a 400.

BoltzGen: binders against a protein, ligand or nucleic acid¶

curl -s -X POST https://api.japanfold.aiand.com/v1/designs \
  -H "Authorization: Bearer $JAPANFOLD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "protocol":"nanobody-anything",
    "name":"my-nanobodies",
    "spec":"entities:\n  - protein: {id: B, sequence: 80..120}\n  - protein: {id: A, msa: empty, sequence: MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQ}\n",
    "params":{"num_designs":10,"budget":10,"fast":true}
  }'

spec (required): a BoltzGen YAML spec under entities:, the binder to design (sequence: 80..120 is a length range) and the target. This is not the sequences: YAML a prediction takes. To aim at an epitope, give the target binding_types: {binding: '45..52'} (1-based residues). A spec the engine would reject (unknown keys, no chain to design, pocket constraints) is refused with a 400 at submit, before it is queued or billed.
protocol (required): what to design.
params: num_designs, budget, fast, seed. See Models & limits.
name: optional label.

`protocol`	Designs
`protein-anything`	De novo mini-protein binder against any target.
`peptide-anything`	Short peptide binder.
`nanobody-anything`	Single-domain antibody / nanobody (VHH).
`antibody-anything`	Antibody binder.
`protein-small_molecule`	Protein binder with a binding-affinity step.
`protein-redesign`	Re-design residues of an existing binder.

Crop the target to the part you want bound, about 512 residues or fewer. A larger target still runs and the designs still dock, but far fewer of them refold into the shape they were drawn as. Measured on this hardware with eight designs per cell, GroEL cropped to 512 residues gave a median refold RMSD of 0.9 Å, five of eight under 2 Å; the same target at 1536 residues gave 15.6 Å and none under 4 Å. Which window you keep can matter as much as its length: on glycogen phosphorylase, two 512-residue windows 100 residues apart gave 4.7 Å and 17.8 Å. If a target designs badly, try another window before asking for more designs.

Submits accept the same Idempotency-Key and Prefer: wait headers as predictions.

RFdiffusion3: all-atom design against a structure¶

RFdiffusion3 diffuses protein structure and sequence together, conditioned on a target structure you provide:

curl -s -X POST https://api.japanfold.aiand.com/v1/designs \
  -H "Authorization: Bearer $JAPANFOLD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "protocol":"rfd3-binder",
    "name":"my-rfd3-binders",
    "structure":"<the contents of your PDB or mmCIF file>",
    "contig":"A1-150,60-80",
    "params":{"num_designs":4,"num_timesteps":100}
  }'

structure (required): the target as PDB or mmCIF text. Paste the file contents, up to 1,100,000 characters (about a 1,600-residue PDB).
contig (required): comma-separated segments. A chain-range like A1-150 keeps those residues fixed; a bare number like 60-80 designs that many new residues. So "A1-150,60-80" keeps target chain A, then designs a 60 to 80 residue binder.
Size: the contig, not the paste, sets how big the run is. Motif plus designed residues has to come to 1,536 or fewer, so a large structure is fine as long as the contig selects less of it.
params: num_designs, num_timesteps, seed. See Models & limits.

`protocol`	Designs
`rfd3-binder`	Binder against a protein target structure.
`rfd3-scaffold`	Scaffold around a fixed functional motif: list the motif residues, design between them.
`rfd3-na-binder`	Binder against a fixed DNA or RNA structure.

RFdiffusion3 designs are unranked: there is no refold-and-filter step, so you get one mmCIF per design with no confidence scores. To check one, fold its sequence back onto the target with a prediction and read the interface confidence (iptm).

PXDesign: binder backbones against a structure¶

PXDesign conditions on a distogram of the target chains you name and generates binder backbones. It is the fastest of the three and the least finished output: coordinates only, no sequence, no ranking, no confidence score. Run the backbones through a sequence-design tool before ordering anything. For a ranked, sequenced binder use BoltzGen.

curl -s -X POST https://api.japanfold.aiand.com/v1/designs \
  -H "Authorization: Bearer $JAPANFOLD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "protocol":"pxdesign-binder",
    "structure":"<the contents of your PDB or mmCIF file>",
    "chains":"A",
    "binder_length":80,
    "hotspots":"A74,A75,A76",
    "params":{"num_designs":4,"n_step":200}
  }'

chains names the target chains to condition on, binder_length is the residue count of the binder to generate (8 to 200), and hotspots is optional: target residues the binder should aim at. One protocol, pxdesign-binder. Only the named chains count toward the size ceiling, and the binder counts too: their sum has to be 1,536 or fewer, so a large file is fine if you name one small chain.

Reading designs¶

Wait on GET /v1/jobs/{id}?wait=60 until succeeded, then read GET /v1/jobs/{id}/results for the designs and their structure artifacts, or GET /v1/jobs/{id}/archive for everything as one zip. See Jobs → Results and Examples.