Protein Design · Backbone design

RFdiffusion3 API

Generates protein backbone coordinates around proteins, small molecules, nucleic acids, and metals. Given geometric and other constraints, specifies backbone geometry. A useful first step in a protein design pipeline. Very well documented!

RFdiffusion3 is a practical first step in protein design workflows: It generates coordinates of the backbone atoms for a protein based on contraints (For example, to spacially deconflict with specific molecules). Its output can be fed into ProteinMPNN or LigandMPNN to generate an amino acid sequence.

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

Submit POST /api/rfd3/

Queues a run and returns 202 with the job.

Schema GET /api/rfd3/

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.

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

Example presets

Send {"preset": "unconditional_monomer"} 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
`unconditional_monomer`	Official example. One design per run. Source ↗
`demo`	Runs every named configuration in demo.json, with one design per configuration. Source ↗
`demo/M0255_1mg5_unfixed`	Official example with its bundled input structure. One design per run. Source ↗
`demo/partial_diffusion`	Official example with its bundled input structure. One design per run. Source ↗
`demo/dsDNA_basic`	Official example with its bundled input structure. One design per run. Source ↗
`enzyme_design`	Runs every named configuration in enzyme_design.json, with one design per configuration. Source ↗
`enzyme_design/M0255_1mg5_unfixed`	Official example with its bundled input structure. One design per run. Source ↗
`na_binder_design`	Runs every named configuration in na_binder_design.json, with one design per configuration. Source ↗
`na_binder_design/dsDNA_basic`	Official example with its bundled input structure. One design per run. Source ↗
`na_binder_design/ssDNA_basic`	Official example with its bundled input structure. One design per run. Source ↗
`na_binder_design/ssDNA_diffused_from_dsDNA_pdb`	Official example with its bundled input structure. One design per run. Source ↗
`na_binder_design/RNA_basic`	Official example with its bundled input structure. One design per run. Source ↗
`na_binder_design/dsDNA_complex`	Official example with its bundled input structure. One design per run. Source ↗
`protein_binder_design`	Runs every named configuration in protein_binder_design.json, with one design per configuration. Source ↗
`protein_binder_design/insulinr`	Official example with its bundled input structure. One design per run. Source ↗
`protein_binder_design/pdl1`	Official example with its bundled input structure. One design per run. Source ↗
`sm_binder_design`	Runs every named configuration in sm_binder_design.json, with one design per configuration. Source ↗
`sm_binder_design/buried`	Official example with its bundled input structure. One design per run. Source ↗
`sm_binder_design/partial`	Official example with its bundled input structure. One design per run. Source ↗
`symmetry`	Runs every named configuration in symmetry.json, with one design per configuration. Source ↗
`symmetry/uncond_C5`	Official example. One design per run. Source ↗
`symmetry/uncond_D4`	Official example. One design per run. Source ↗
`symmetry/unindexed_C2_1j79`	Official example with its bundled input structure. One design per run. Source ↗
`symmetry/unindexed_C2_1e3v`	Official example with its bundled input structure. One design per run. Source ↗
`symmetry/indexed_unsym_C2_1bfr`	Official example with its bundled input structure. One design per run. Source ↗
`symmetry/unsym_C3_6t8h`	Official example with its bundled input structure. One design per run. Source ↗

These local CLI options are not applicable to Bio Web and are omitted from its inputs:

out_dir: Bio Web creates a separate output directory for each run and collects its result files.
ckpt_path: Bio Web uses the installed RFD3 checkpoint configured on the server.
skip_existing: Each web run starts with a fresh output directory, so there are no existing designs to skip.

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
`inputs`	string textarea	no	`{ "design": { "length": "150-150", "is_non_loopy": true } }`	Inputs (JSON or YAML) The path and file name of the JSON or YAML file where you have defined your inference constraints. In this form: Enter the JSON or YAML contents here. Use "input": "uploaded" to reference the structure upload. Presets may use a bundled bio-tools://rfd3/ reference or an official ../input_pdbs/ example path. Enter null with specification overrides for an override-only design.
`spec_input_file`	string file	no	`—`	Input structure (uploaded) Optional PDB or mmCIF for configurations with "input": "uploaded". file types .pdb,.cif,.ent.
`inputs_file`	string file	no	`—`	Inputs file (JSON or YAML) The path and file name of the JSON or YAML file where you have defined your inference constraints. In this form: Choose a JSON or YAML file. Use "input": "uploaded" to reference the structure upload, or keep a bundled bio-tools://rfd3/ reference from a preset. file types .json,.yaml,.yml.
`input`	string file	no	`—`	Input structure Path to and file name of PDB/CIF. Required if you provide contig+length. In this form: Choose a PDB or mmCIF file. Presets include their input structures; a new upload replaces the included file. file types .pdb,.cif,.ent.
`contig`	string text	no	`—`	Contig (Can only pass a contig string.) Indexed motif specification, e.g., "A1-80,10,/0,B5-12". Residues whose position/order in the final sequence is specified.
`unindex`	string textarea	no	`—`	Unindex (Can only pass a contig string or dictionary.) Unindexed motif components, the specified residues can be anywhere in the final sequence. See Unindexing Specifics for more information. Which residues should have their index be inferred by the model instead of prespecified
`length`	string text	no	`150`	Length Total design length constraint; "min-max" or int for specified length.
`ligand`	string text	no	`—`	Ligand Ligand(s) by chemical component name (from RSCB PDB) or index. These are ligands built in to the source mmCIF file, using the identifiers specified there
`cif_parser_args`	string textarea	no	`{}`	CIF parser args Optional args to CIF loader. See CIF parser options for more information. In this form: Enter a JSON object. The local cache_dir option is not available, and extra_fields is accepted only alongside an mmCIF structure because the PDB reader ignores it.
`extra`	string textarea	no	`{}`	Extra Extra metadata (e.g., logs). Current options include sampled_contig.
`dialect`	string select	no	`2`	Dialect 2=new (default), 1=legacy, Learn more about the legacy parsing system by looking at input_parsing.py. One of: `2`, `1`.
`select_fixed_atoms`	string textarea	no	`—`	Select fixed atoms Atoms with fixed coordinates. See the Select Fixed Atoms subsection for more information. Dictionary that indicated which atoms should be fixed (can use ALL, BKBN, or TIP for all atoms in the residue, backbone atoms only and tip atoms only In this form: Name a ligand by its chemical component code, such as NAI, rather than by chain and residue number. A ligand written into a chain that also holds polymer residues is moved onto a chain of its own while the structure is parsed, so a chain-and-number reference to it no longer matches.
`select_unfixed_sequence`	string textarea	no	`—`	Select unfixed sequence Where sequence can change. Default is True - all input regions have fixed sequences. Contig string input specifies components to unfix the sequence for. Dictionary inputs are allowed but not recommended.
`select_buried`	string textarea	no	`—`	Select buried Selection of RASA (Relatively Accessible Surface Area) for buried, partially buried, and exposed conditioning, respectively. Only contig string and dictionary are acceptable inputs.
`select_partially_buried`	string textarea	no	`—`	Select partially buried Selection of RASA (Relatively Accessible Surface Area) for buried, partially buried, and exposed conditioning, respectively. Only contig string and dictionary are acceptable inputs.
`select_exposed`	string textarea	no	`—`	Select exposed Selection of RASA (Relatively Accessible Surface Area) for buried, partially buried, and exposed conditioning, respectively. Only contig string and dictionary are acceptable inputs.
`select_hbond_donor`	string textarea	no	`—`	Select hbond donor Atom-wise donor/acceptor flags. Atom-wise selection of hydrogen bond donors and acceptors, respectively. Only dictionary inputs allowed. See RFdiffusion3 — Nucleic acid binder design examples for an example.
`select_hbond_acceptor`	string textarea	no	`—`	Select hbond acceptor Atom-wise donor/acceptor flags. Atom-wise selection of hydrogen bond donors and acceptors, respectively. Only dictionary inputs allowed. See RFdiffusion3 — Nucleic acid binder design examples for an example.
`select_hotspots`	string textarea	no	`—`	Select hotspots Atom-level or residue-level hotspots. Hotspots will typically be at most 4.5 Å to any heavy atom in the designed structure. Typically used for designing binders.
`redesign_motif_sidechains`	boolean checkbox	no	`false`	Redesign motif sidechains Fixed backbone, redesigned sidechains for motifs (input structures).
`symmetry`	string textarea	no	`—`	Symmetry See Overview of Symmetry in RFD3. In this form: Enter SymmetryConfig as JSON, for example {"id": "C3", "is_symmetric_motif": true}.
`ori_token`	string text	no	`—`	Ori token [x,y,z] origin override to control COM (center of mass) placement of designed structure.
`infer_ori_strategy`	string select	no	`—`	Infer ori strategy "com" or "hotspots". The center of mass of the diffused region will typically be within 5Å of the ORI token. Using hotspots will place the ORI token 10Å outward from the center of mass of the specified hotspots. Using com will place the token at the center of mass of the input structure. One of: `(empty)`, `com`, `hotspots`.
`plddt_enhanced`	boolean checkbox	no	`true`	pLDDT enhanced Default True. Enables pLDDT (predicted Local Distance Difference Test) enhancement.
`is_non_loopy`	string select	no	`—`	Is non loopy Default None. If True/False, produces output structures with fewer/more loops. One of: `(empty)`, `true`, `false`.
`partial_t`	number number	no	`—`	Partial t (angstroms) Noise (Å) for partial diffusion, enables partial diffusion (sets the noise level.) Recommended values are 5.0-15.0 Å. See Partial Diffusion for more information. minimum 0, step 0.5.
`allow_ligand_on_existing_chain`	boolean checkbox	no	`false`	Allow ligand on existing chain Allow the shared ligand chains used by some official input structures. This is enabled in presets that require it. In this form: Accepting such a structure logs a warning that the shared chain is being separated, which is expected. The ligands end up on a chain of their own, so select them by chemical component code.
`job_name`	string text	no	`rfd3-demo`	Job name
`n_batches`	number number	no	`1`	Batches number of batches to generate per input key (default: 1). minimum 1, maximum 100.
`diffusion_batch_size`	number number	no	`8`	Designs per batch number of diffusion samples (designs) per batch (default: 8). If n_batches=1 and diffusion_batch_size=8 then 8 designs will be generated from the inference run. minimum 1, maximum 64.
`inference_sampler.num_timesteps`	number number	no	`200`	inference_sampler.num_timesteps diffusion timesteps for sampling (default: 200). minimum 20, maximum 1000.
`inference_sampler.step_scale`	number number	no	`1.5`	inference_sampler.step_scale scales diffusion step size; higher → less diverse, more designable (default: 1.5). minimum 0.1, maximum 10, step 0.1.
`low_memory_mode`	boolean checkbox	no	`false`	Low-memory mode memory-efficient tokenization mode; set True if GPU RAM is tight (default: False).
`dump_trajectories`	boolean checkbox	no	`false`	Save trajectories If True, the trajectory files are also saved to the specified output directory (default: False).
`specification`	string textarea	no	`{}`	Specification overrides (JSON) JSON overrides for the per-example InputSpecification (default: {}). For example, you can run rfd3 design inputs=null specification.length=200 for a quick debug of creating a 200-length protein.
`global_prefix`	string text	no	`—`	Global prefix This setting allows you to change the beginning of the name of the output files from the name of the input JSON or YAML file to your own string (default: null). In this form: Leave blank for the default. Enter "" to omit the prefix. Use letters, digits, dots, underscores or hyphens.
`prevalidate_inputs`	boolean checkbox	no	`false`	Prevalidate inputs Check that your inputs (JSON or YAML file) are valid before running inference (default: False).
`inference_sampler.gamma_0`	number number	no	`0.6`	inference_sampler.gamma_0 This value (default: 0.6) influences the diversity of the designs from RFD3. A lower value increases designability but decreases diversity. minimum 0, maximum 1, step 0.05.
`json_keys_subset`	string textarea	no	`—`	JSON keys subset Allows the user to extract only a subset of the JSON keys provided in the inputs file (default: null).
`inference_sampler.n_recycle`	number number	no	`—`	inference_sampler.n_recycle Number of recycling iterations per diffusion step (default: null, uses the model checkpoint default of 2). Recycling allows the network to refine its predictions iteratively within each denoising step. minimum 0, step 1.
`inference_sampler.kind`	string select	no	`auto`	inference_sampler.kind Change this value to symmetry (default: default) to turn on symmetry mode for the inference sampler. In this form: Automatic selects the sampler from the input specification. One of: `auto`, `default`, `symmetry`.
`inference_sampler.cfg_features`	string textarea	no	`active_donor, active_acceptor, ref_atomwise_rasa`	inference_sampler.cfg_features The values specified (options are active_donor, active_acceptor, or ref_atomwise_rasa) are set to 0 for classifier-free guidance. Classifier-free guidance is how the diffusion model can steer the calculation towards a condition without training a separate classifier.
`inference_sampler.use_classifier_free_guidance`	boolean checkbox	no	`false`	inference_sampler.use_classifier_free_guidance If set to True, RFD3 can use classifier-free guidance to guide the system towards a condition without training a separate classifier (default: False).
`inference_sampler.cfg_t_max`	number number	no	`—`	inference_sampler.cfg_t_max The maximum time to apply classifier-free guidance to the inference run (default: null). minimum 0, step 0.001.
`inference_sampler.cfg_scale`	number number	no	`1.5`	inference_sampler.cfg_scale Controls the influence of the classifier-free guidance adjustment (default: 1.5). minimum 0, step 0.001.
`inference_sampler.center_option`	string select	no	`all`	inference_sampler.center_option Specifies how to center the coordinates during the inference run to ensure that structures are alined around a specific point. Options include: all — (default) Uses the center of mass (COM) of all atoms motif — Uses the COM of the motif atoms with fixed coordinates diffuse — Uses the COM of all fixed coordinates that are not part of motif atoms One of: `all`, `motif`, `diffuse`.
`inference_sampler.s_trans`	number number	no	`1.0`	inference_sampler.s_trans Translational noise scale for augmentation during inference (default: 1.0). minimum 0, step 0.001.
`inference_sampler.allow_realignment`	boolean checkbox	no	`false`	inference_sampler.allow_realignment If set to True (default: False) then the noised structure can be realigned during inference based on the location of a given motif. From Issue #154: It is generally not needed to include this option, there are fewer ‘weird’ interactions with motif scaffolding when it’s set to False.
`inference_sampler.noise_scale`	number number	no	`1.003`	inference_sampler.noise_scale This parameter sets the scaling for the noise during inference (default 1.003). A smaller value will lead to less noise in your system leading to less diversity in the outputs. minimum 0, step 0.001.
`inference_sampler.p`	number number	no	`7`	inference_sampler.p Determines the ‘shape’ of the noise schedule (default: 7). minimum 0.001, step 0.001.
`inference_sampler.gamma_min`	number number	no	`1.0`	inference_sampler.gamma_min Controls when gamma_0 is used, if t>gamma_min, gamma_0 is used as the value of gamma, which influences the diversity of the designs from RFD3. minimum 0, step 0.001.
`inference_sampler.s_jitter_origin`	number number	no	`0.0`	inference_sampler.s_jitter_origin Controls the standard deviation of the Gaussian distribution that is used to ‘jitter’ the motif offset (default: 0.0, no jitter). minimum 0, step 0.001.
`cleanup_guideposts`	boolean checkbox	no	`true`	Cleanup guideposts Set to False (default: True) to save the guideposts used during inference, see Debugging recommendations for more information.
`cleanup_virtual_atoms`	boolean checkbox	no	`true`	Cleanup virtual atoms Set to False (default: True) to save information about the diffused virtual atoms used during inference. RFD3 uses virtual atoms to account for the different number of atoms in side chains during the design process. RFD3 is atom based, however the number of atoms in a residue will differ based on its side chain, which is only determined after some diffusion steps have occurred, meaning virtual atoms are necessary for those steps. See Debugging recommendations for more information.
`read_sequence_from_sequence_head`	boolean checkbox	no	`true`	Read sequence from sequence head Used during training, it is not recommended to change this setting (default: True).
`output_full_json`	boolean checkbox	no	`true`	Output full JSON Output all specification information to the JSON file that gets created for each design (default: True).
`dump_prediction_metadata_json`	boolean checkbox	no	`true`	Dump prediction metadata JSON If True, the metadata for the inference run will be included in the output JSON file (default: True).
`align_trajectory_structures`	boolean checkbox	no	`false`	Align trajectory structures Aligns the structures in the output trajectories (default: False).

Example

A request that runs

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

curl -X POST https://athanortools.com/api/rfd3/ \
  -H 'Content-Type: application/json' \
  -d '{
  "input_mode": "parameters",
  "input": "",
  "contig": "",
  "unindex": "",
  "length": "150",
  "ligand": "",
  "cif_parser_args": "{}",
  "extra": "{}",
  "dialect": "2",
  "select_fixed_atoms": "",
  "select_unfixed_sequence": "",
  "select_buried": "",
  "select_partially_buried": "",
  "select_exposed": "",
  "select_hbond_donor": "",
  "select_hbond_acceptor": "",
  "select_hotspots": "",
  "redesign_motif_sidechains": false,
  "symmetry": "",
  "ori_token": "",
  "infer_ori_strategy": "",
  "plddt_enhanced": true,
  "is_non_loopy": "",
  "partial_t": "",
  "allow_ligand_on_existing_chain": false,
  "job_name": "rfd3-demo",
  "n_batches": 1,
  "diffusion_batch_size": 8,
  "inference_sampler.num_timesteps": 200,
  "inference_sampler.step_scale": 1.5,
  "low_memory_mode": false,
  "dump_trajectories": false,
  "specification": "{}",
  "global_prefix": "",
  "prevalidate_inputs": false,
  "inference_sampler.gamma_0": 0.6,
  "json_keys_subset": "",
  "inference_sampler.n_recycle": "",
  "inference_sampler.kind": "auto",
  "inference_sampler.cfg_features": "active_donor, active_acceptor, ref_atomwise_rasa",
  "inference_sampler.use_classifier_free_guidance": false,
  "inference_sampler.cfg_t_max": "",
  "inference_sampler.cfg_scale": 1.5,
  "inference_sampler.center_option": "all",
  "inference_sampler.s_trans": 1.0,
  "inference_sampler.allow_realignment": false,
  "inference_sampler.noise_scale": 1.003,
  "inference_sampler.p": 7,
  "inference_sampler.gamma_min": 1.0,
  "inference_sampler.s_jitter_origin": 0.0,
  "cleanup_guideposts": true,
  "cleanup_virtual_atoms": true,
  "read_sequence_from_sequence_head": true,
  "output_full_json": true,
  "dump_prediction_metadata_json": true,
  "align_trajectory_structures": 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.
`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.