> This page is for RFD4-Proteina, version 1.0.0 (Latest) (default).
> For other versions, use one of these documentation indexes:
> - 1.0.0 (Latest) (default): https://docs.nvidia.com/nim/bionemo/rfd4-proteina/1.0.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nim/bionemo/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nim/bionemo/_mcp/server.

# Generate protein designs

POST https://health.api.nvidia.com/v1/biology/ipd/rfd4-proteina/generative
Content-Type: application/json

Reference: https://docs.nvidia.com/nim/bionemo/rfd4-proteina/api-reference/generate-rfd-4-proteina-designs

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Headers

- `X-Include-Runtime-Metrics` (boolean, optional, default: false) — When true, each design carries a per-stage timing breakdown in runtime_metrics: pre-process / model forward / post-process / metrics / total. Off by default. The stages are measured either way, so turning this on does not change the latency it reports. Same header name and same key names as the OpenFold2 and OpenFold3 NIMs, so one benchmark client reads all three.

### Body (application/json)

This endpoint expects a DesignRequest.

- `task` (enum, required) — Which design task to run. Selects the sampler path and the validation rules.
  - Allowed values: `generation`, `motif_scaffolding`, `enzyme_design`, `small_molecule_binder`, `antibody_design`, `partial_diffusion`, `inverse_folding`
- `input` (DesignRequestInput, required) — Input specification in one of the three supported dialects.
- `sampling` (SamplingOptions, optional) — Rollout controls.
- `partial` (PartialDiffusionOptions, optional, nullable) — Start times, required by partial_diffusion and rejected for every other task.
- `search` (SearchOptions, optional, nullable) — Reward-guided search. Absent means plain sampling.
- `metrics` (MetricsOptions, optional) — Metric families to report.
- `output` (OutputOptions, optional) — Response content controls.

## Response

### 200

Successful Response

- `request_id` (string, required) — Server-assigned id, also logged on every line for this request.
- `task` (enum, required) — Task that ran.
  - Allowed values: `generation`, `motif_scaffolding`, `enzyme_design`, `small_molecule_binder`, `antibody_design`, `partial_diffusion`, `inverse_folding`
- `model` (api__dto__response__ModelInfo, required) — Weights and device that produced the designs.
- `runtime` (RuntimeInfo, required) — Software stack and acceleration settings that ran them.
- `schedule` (ScheduleReport, required) — Sampler configuration actually integrated.
- `designs` (list of DesignRecord, required) — Generated designs. Equals num_replicates for plain sampling. Under search it can be larger (kept intermediates) or smaller (pruned branches), so read the count, do not assume it.
- `duration_ms` (double, required) — Wall time for the whole request.
- `search` (SearchReport, optional, nullable) — Search behaviour, when a search block was sent.
- `aggregated_metrics` (list of AggregatedMetric, optional) — Per-design metrics reduced across the request. Empty when no metrics were requested. Rows whose key ends in '.pass' carry the in-silico success rate.
- `warnings` (list of string, optional) — Non-fatal conditions: designs dropped by a filter, requested metrics that did not apply.

## Errors

### 400 Bad Request Error

Bad Request

- `error` (ErrorBody, required) — What went wrong.

### 413 Content Too Large Error

Request Entity Too Large

- `error` (ErrorBody, required) — What went wrong.

### 422 Unprocessable Entity Error

Unprocessable Entity

- `error` (ErrorBody, required) — What went wrong.

### 499 Client Closed Request Error

Additional Response

- `error` (ErrorBody, required) — What went wrong.

### 500 Internal Server Error

Internal Server Error

- `error` (ErrorBody, required) — What went wrong.

### 503 Service Unavailable Error

Service Unavailable

- `error` (ErrorBody, required) — What went wrong.

### 504 Gateway Timeout Error

Gateway Timeout

- `error` (ErrorBody, required) — What went wrong.

## Types

### DesignRequestInput

Input specification in one of the three supported dialects.

- `format`: `annotated_cif` (AnnotatedCifInput)
  - `file` (InlineFile, required) — Annotated mmCIF written by the upstream authoring tools.
  - `example_id` (string, optional, default: design) — Identifier echoed into design ids.
- `format`: `condition_spec` (ConditionSpecInput)
  - `files` (list of InlineFile, required) — Structures the spec refers to by name.
  - `spec` (map from string to any, required) — One condition-spec example: input, optional contig, and conditions.
  - `example_id` (string, optional, default: design) — Identifier echoed into design ids.

### SamplingOptions

Per-request rollout controls. The integrator and noise scales come from the checkpoint's released configuration and are deliberately not exposed: they are what the reported quality numbers were measured with. The step count and the recycle schedule are exposed, because they are what a caller trades runtime against quality with -- but only the three named schedules have been validated against the checkpoint, and a custom one says so in ``warnings``.

- `num_steps` (integer, optional, nullable) — Integration steps. Omit num_steps, recycle_strategy and recycle_schedule to inherit the loaded upstream inference preset, including recycling. An explicit num_steps on its own requests flat sampling with one trunk evaluation per step. A recycle_strategy or recycle_schedule carries its own step count, so num_steps may be omitted with either. Sent beside a recycle_strategy it wins: the strategy contributes only its recycle shape, rescaled onto this many steps, and warnings names what it was stretched from. Sent beside an explicit recycle_schedule it must equal the band widths' sum, because bands a caller wrote are taken literally. The resolved values are reported in ScheduleReport. The 1-1000 bound is the contract's: the loaded checkpoint imposes its own higher minimum on flat sampling, and a num_steps below it is refused with invalid_input naming that minimum rather than run. A recycle_strategy always satisfies it.
- `recycle_strategy` (enum, optional, nullable) — Named recycle schedule. Recycling runs the trunk more than once within a sampling step, spending the extra passes where the fold is decided. A strategy carries its own step count: 'thinking_low' is 60 steps and 110 trunk passes, 'thinking_medium' 60 steps and 185 passes (the checkpoint's default), 'thinking_high' 60 steps and 295 passes. Runtime scales with trunk passes, not steps. A value that is not one of these runs 'thinking_medium' and says so in warnings. A num_steps that disagrees with the strategy's own count is not refused: it wins, and the strategy's depths are rescaled onto it -- only 60 steps is validated for these shapes, so warnings says what a shorter one costs. Cannot be combined with recycle_schedule.
  - Allowed values: `thinking_low`, `thinking_medium`, `thinking_high`
- `recycle_schedule` (list of list of string, optional, nullable) — Custom recycle schedule as [steps, recycle_depth] bands that cover the trajectory in order, for example [[5, 1], [5, 2], [10, 6], [40, 1]]. The step counts add up to the number of integration steps, so num_steps may be omitted, and that total is held to the same checkpoint minimum as a flat num_steps. Each depth is the number of times the trunk is re-run within a step (0 runs it once). Only the named strategies have been validated against the checkpoint; the quality of any other schedule is not known, and the response says so in warnings. Cannot be combined with recycle_strategy.
- `num_replicates` (integer, optional, default: 1) — Independent designs from this one specification. Unbounded on purpose: with the batched default every replicate shares one forward pass, so what a request can ask for is a property of the GPU and the token count, not a number a schema can know. Too many for the GPU is a 413 naming this field, not a 422.
- `batch_size` (integer, optional, nullable) — Replicates evaluated in one forward pass. Omit it -- the default -- and every replicate this request asks for runs in one batch, which is the fastest way to serve them. Set it lower to trade that back for one of the two things a batch costs. The first is replay: a batch draws its noise from a single RNG stream, so which design a row becomes depends on the batch it was produced in, and only batch_size 1 lets a design be reproduced on its own. The second is memory, which grows with it -- a replicate count that fits at 1 can exhaust the GPU in one batch. Replicates run in consecutive batches of this size, so a count that is not a multiple of it leaves a smaller final batch whose designs differ from what the same indices would have been in a full one; DesignDiagnostics.batch_size reports what each design actually ran in.
- `seed` (integer, optional, nullable) — Base seed. Replicates run batched by default, and a batch draws every member from one stream seeded once: the designs still differ from each other, but the seed identifies the batch rather than the design, so the whole request replays and a single design does not. Set sampling.batch_size to 1 for the other behaviour, where replicate i runs with (seed+i) modulo 2**63 and each design replays on its own. Omit for a fresh random base seed. Replay requires the same input, weights, backend, runtime and batch_size; GPU determinism is not guaranteed.

### PartialDiffusionOptions

Where on the schedule a partial-diffusion rollout starts.

- `trajectory_fraction_steps` (double, optional, nullable) — Run this fraction of the trajectory, deriving both start times. Mutually exclusive with t_*.
- `t_backbone` (double, optional, nullable) — Backbone start time.
- `t_latent` (double, optional, nullable) — Sequence-latent start time.
- `couple_partial_t` (boolean, optional, default: false) — Derive the unsupplied modality's start time from the supplied one.

### SearchOptions

Reward-guided beam search over the diffusion trajectory. Not best-of-N. At each checkpoint every surviving candidate is branched, each branch is rolled out to a clean structure to be scored, and the best ``beam_width`` survive to continue. Compute concentrates on trajectories that are going somewhere, which is why it beats filtering at equal budget. Cost is roughly ``beam_width * n_branch * (len(step_checkpoints) - 1)`` rollouts per replicate; the deployment enforces its own ceiling on that. Memory is a second axis: every candidate at a checkpoint is decoded to be scored, so ``scoring_chunk_size`` bounds the peak without changing what comes back.

- `step_checkpoints` (list of integer, required) — Steps at which to branch and prune. Starts at 0, strictly increasing, ends at num_steps.
- `reward_metrics_tags` (list of enum, required) — Tags gating which metrics run while scoring candidates. Independent of MetricsOptions.tags.
  - Allowed values: `design`, `hotspot_conditioning`, `rasa_conditioning`, `centroid_conditioning`, `interchain_interactions`, `3d_coordinate_conditioning`, `internal_coordinate_conditioning`, `unindexed`, `partial_diffusion`, `small_molecule_only`, `no_ligand`, `cms`, `cath`, `structure_prediction`, `developability`, `unconditional_refolding`, `ppi_refolding`, `antibody`, `motif_scaffold_refolding`, `internal_coordinate_motif_scaffold_refolding`, `sm_binder_refolding`, `dna_refolding`, `apo_refolding`, `ame_refolding`, `ame_no_ligand_refolding`, `disco_refolding`
- `weights` (map from string to double, required) — Weight per 'metric.output_key'. The reward is the weighted sum; negative weights penalise.
- `n_branch` (integer, optional, default: 2) — Branches generated per surviving candidate at a checkpoint.
- `beam_width` (integer, optional, default: 3) — Candidates kept after each checkpoint. All survivors return.
- `clip_values` (map from string to map from string to double, optional) — Per-key bounds applied before weighting, so a term stops contributing past the bound. Reported metric values are unaffected. This is how a multi-objective search stops one term from dominating.
- `checkpoint_overrides` (map from string to RewardOverride, optional) — Reward changes taking effect at a checkpoint, keyed by step.
- `intermediate_save_min_reward` (double, optional, nullable) — Also return non-surviving scoring rollouts whose search.reward reaches this value. Those structures are already paid for, so keeping the good ones raises successes per GPU-hour, and a threshold says which are good where a boolean could only say 'all' or 'none'. Omit to return the final beam alone. Setting it makes the design count exceed num_replicates.
- `scoring_chunk_size` (integer, optional, nullable) — Decoded rows per scoring chunk. A checkpoint scores beam_width * n_branch * num_replicates candidates at once, and decoding all of them holds every one in memory simultaneously; this bounds that without changing the result. Omit to score the whole candidate tensor in one go.

### MetricsOptions

Which metric families to compute and report per design. Empty means diagnostics only. Metrics are gated by tag, not named individually, which is how the upstream metric set works; an unknown tag would silently compute nothing, so only known tags are accepted.

- `tags` (list of enum, optional) — Metric families to compute. Design tags and refolding tags are separate namespaces.
  - Allowed values: `design`, `hotspot_conditioning`, `rasa_conditioning`, `centroid_conditioning`, `interchain_interactions`, `3d_coordinate_conditioning`, `internal_coordinate_conditioning`, `unindexed`, `partial_diffusion`, `small_molecule_only`, `no_ligand`, `cms`, `cath`, `structure_prediction`, `developability`, `unconditional_refolding`, `ppi_refolding`, `antibody`, `motif_scaffold_refolding`, `internal_coordinate_motif_scaffold_refolding`, `sm_binder_refolding`, `dna_refolding`, `apo_refolding`, `ame_refolding`, `ame_no_ligand_refolding`, `disco_refolding`

### OutputOptions

Response content controls.

- `structure_format` (enum, optional, default: mmcif) — Structure encoding, or 'none' to omit structures.
  - Allowed values: `mmcif`, `none`
- `include_sequence` (boolean, optional, default: true) — Return the designed one-letter protein sequence.

### api__dto__response__ModelInfo

Weights and runtime that produced a response. Log this with every batch of designs; it is the reproducibility record. A result is only comparable against another with the same checkpoints, dtype and backend — the numerics differ across execution paths.

- `model_name` (string, required) — Model family name.
- `checkpoint` (string, required) — Latent-diffusion checkpoint the velocity trunk was loaded from.
- `autoencoder_checkpoint` (string, required) — Partial-autoencoder checkpoint for the encoder and decoder.
- `device` (string, required) — Torch device the model runs on.
- `dtype` (string, required) — Trunk compute dtype.
- `num_residue_types` (integer, required) — Decoder sequence classes: 20 protein-only, 33 unified.
- `package_version` (string, required) — Serving package version.
- `execution_backend` (enum, optional, default: bioir) — Which trunk ran, and how. 'oss_eager' is the upstream reference network uncompiled; 'oss_torch_compile' is the same network under torch.compile, padded to token buckets; 'bioir' is the accelerated trunk with its own kernels. Every other stage is identical across the three, but outputs are not bit-comparable: compilation and BioIR's kernels both change numerics. Which one is fastest depends on size -- the OSS paths win below roughly 250 tokens and BioIR above roughly 650.
  - Allowed values: `oss_eager`, `oss_torch_compile`, `bioir`
- `oracle` (list of string, optional) — Refolding oracle(s) active for this request, by name, e.g. \['oracle\_my\_predictor']. There is no built-in oracle -- this is empty unless a reward.py mounted on the deployment declares one or more. Any number may run at once, each independently gated by its own tags and prefixing its own metrics ('\<name>.\*'); without this list a metric key's provenance is not otherwise recoverable, and two oracles' pLDDTs are not comparable without knowing which predictor produced each. Empty when no refolding ran.

### RuntimeInfo

The software stack and acceleration settings that produced this answer. Reported on every response because a bug report without it costs a round trip, and because the absence of a package is often the whole explanation. Read together with ``model``: that says which weights and which trunk, this says which build ran them and how.

- `nim_version` (string, required) — Deployment version, from the image's VERSION file. NIM_MODEL_VERSION overrides it.
- `packages` (map from string to string, required) — Installed versions of the libraries that decide behaviour. A null means the package is *not installed*, which is reported rather than omitted: a missing 'cuequivariance_ops_torch' is why pair-bias attention runs unfused.
- `limits` (RuntimeLimits, required) — Deployment limits in force for this request.
- `nimtools_version` (string, optional, nullable) — nimtools version baked into the image.
- `inference_precision` (string, optional, nullable) — Configured outer inference precision: bf16-mixed, 32 or 32-true.
- `bioir_dtype` (string, optional, nullable) — Independent BioIR trunk dtype; null when no component uses BioIR. Outer FP32 does not override this internal dtype.
- `cuda` (string, optional, nullable) — CUDA version torch was built against.
- `gpu` (string, optional, nullable) — Device name of the GPU this request ran on.
- `gpu_count` (integer, optional, default: 0) — GPUs this deployment serves from. Greater than one means a process pool: requests run in parallel, one per GPU. A pooled worker sees a single device, so this is the deployment's count and not the worker's.
- `gpu_ids` (list of integer, optional) — Indices in that pool. Empty when serving in-process.
- `compile_lengths` (list of integer, optional) — Eligible token buckets for torch.compile. This is policy, not observed compilation counts.
- `cuda_graphs` (boolean, optional, default: false) — Whether a BioIR CUDA graph is currently captured in the loaded model cache; not proof of replay on this request.
- `cuda_graph_cache` (map from string to integer, optional) — Observed BioIR cache totals: active, captured, verified, fallback. Not per-request replay counts.
- `cuda_graph_max_tokens` (integer, optional, default: 0) — Token ceiling for CUDA-graph replay; requests above it run the trunk eager. 0 means no ceiling is reported by this runtime. Graphs are a launch-bound win, so the gain is largest on small shapes and has largely run out by the ceiling.
- `cuda_graph_slots` (integer, optional, default: 0) — How many captured graphs the trunk may hold at once. BioIR keys graphs on shape *and* recycle depth, so a schedule visiting five depths needs five slots or it evicts a graph it is about to want again. 0 means no slot limit is reported by this runtime.

### ScheduleReport

Sampler configuration actually integrated.

- `kind` (enum, required) — Which sampler path ran.
  - Allowed values: `full`, `partial`
- `num_steps` (integer, required) — Steps executed, after any trajectory-fraction scaling.
- `backbone_schedule` (string, required) — Backbone time-grid mode and power.
- `latent_schedule` (string, required) — Sequence-latent time-grid mode and power.
- `recycle_strategy` (string, optional, nullable) — Selected strategy, custom for a client-supplied recycle_schedule, upstream_default for the loaded preset, or null for explicit flat sampling.
- `recycle_schedule` (list of list of string, optional, nullable) — Executed [steps, recycle depth] bands, restricted to the tail for partial diffusion; null uses recycle_depth.
- `recycle_depth` (integer, optional, default: 0) — Constant upstream recycle depth when no bands apply; zero runs the trunk once.
- `trunk_passes` (integer, optional, nullable) — Trunk evaluations across the trajectory. Equals num_steps without recycling and exceeds it with; this, not num_steps, is what runtime scales with.
- `start_times` (map from string to double, optional, nullable) — Resolved per-modality start times for the partial path.

### DesignRecord

One generated design.

- `design_id` (string, required) — Stable id, opaque by contract. Plain sampling gives '\<example\_id>\_\<replicate\_index>'. Under search a search-generated segment appears between the two and the trailing index is a beam position, so a beam of two can return '...\_0' and '...\_2' -- ids are neither dense nor contiguous, and their shape is not a contract. Use 'replicate\_index' and 'origin' to reason about a design; use the request's 'example\_id' to correlate it with what was asked for.
- `replicate_index` (integer, required) — Zero-based replicate this design came from.
- `diagnostics` (DesignDiagnostics, required) — Per-design counters and timings.
- `origin` (enum, optional) — How this design was produced: plain sampling, the final beam, or a kept scoring rollout.
  - Allowed values: `sample`, `search_final`, `search_intermediate`
- `seed` (integer, optional, nullable) — Seed this design was produced under. At batch_size 1 it is the replicate's own seed and the design replays on its own. Designs produced in one batch share that batch's seed: each still receives distinct noise -- a batch draws from one RNG stream and every row takes a different part of it -- but the seed names the batch rather than the design, so replay the whole request at the same batch_size and not a design in isolation. Search survivors and intermediates likewise share the replicate seed; replay the full search, not a survivor on its own. Replay requires the same input, weights, backend, runtime and batch_size; GPU determinism is not guaranteed.
- `sequence` (string, optional, nullable) — Designed protein sequence in one-letter codes; 'X' for non-protein tokens.
- `structure` (StructureFile, optional, nullable) — Design coordinates, omitted on request.
- `search_reward` (double, optional, nullable) — Aggregated reward this design was selected on. Null without search.
- `chain_of_interest` (string, optional, nullable) — The chain every '*_coi' metric is computed about, as 'chain_id_transformation_id'. Null when the design has one chain or the chain of interest was ambiguous. Read it before reading hotspot_obedience or interchain_interactions.*_coi: on a target that is not all-atom conditioned those numbers include the target's own sidechains, so they describe this chain rather than the interface.
- `metrics` (map from string to DesignRecordMetrics, optional) — Requested metrics, keyed '\<metric>.\<output\_key>'; the output part may itself be dotted. Empty when no metric tags were requested. Null values mean the metric did not apply — sequence\_adherence, for one, is undefined when nothing was sequence-conditioned.
- `runtime_metrics` (map from string to double, optional, nullable) — Per-stage wall times in seconds, present only when the request carried X-Include-Runtime-Metrics. Keys match the other BioNeMo NIMs so the same benchmark client reads all of them: preprocess_time_s (featurization, padding to a compile bucket, host-to-device copy), model_forward_time_s (the rollout alone), postprocess_time_s (mmCIF export and sequence extraction), metrics_time_s (the design-metric pass), total_time_s (the whole request). On CUDA it also carries peak_memory_allocated_bytes and peak_memory_reserved_bytes for the forward pass, reset per batch so they describe this one: allocated is what the model asked for and scales with batch size, reserved is what the caching allocator held from the driver, which is what an OOM is measured against. preprocess and model_forward are shared by every design one forward pass produced -- a beam is one trajectory tree, not N independent runs, and a batch of replicates is one pass over all of them -- while postprocess and metrics are genuinely per design. Summing the shared ones across a beam multiplies them by the beam width, and across a batch by DesignDiagnostics.batch_size. A stage that could not be measured is absent, never null and never 0.0.

### SearchReport

What the search actually did. Present only when the request carried a ``search`` block. ``rollouts`` is the honest cost figure: each one is a full trajectory run to a clean structure purely to score a branch.

- `step_checkpoints` (list of integer, required) — Checkpoints at which branching and pruning happened.
- `n_branch` (integer, required) — Branches generated per surviving candidate.
- `beam_width` (integer, required) — Candidates kept after each checkpoint.
- `rollouts` (integer, required) — Trajectories rolled out to completion for scoring.
- `reward_keys` (list of string, required) — Metric keys the reward was computed from, in weight order.
- `best_reward` (double, optional, nullable) — Highest reward among returned designs.
- `intermediates_kept` (integer, optional, default: 0) — Non-surviving scoring rollouts returned alongside the final beam, i.e. those that reached the request's intermediate_save_min_reward. Zero when none was set.
- `completion_rollouts` (integer, optional, default: 0) — Trajectories rolled to a clean structure purely to score a branch. This is where a search spends its time, and it is not the number of designs returned.

### AggregatedMetric

One metric reduced across the designs in this request. Mirrors the `metric,reduction,value,n` columns upstream writes to `aggregated_metrics.csv`, minus its `dataset` column -- that one holds an absolute host path and must not leave the container. This is also where in-silico success rate surfaces. Every pass criterion publishes `{criterion}.pass`, so a row like `("unconditional.pass", "mean", 0.4, 10)` reads as four designs in ten meeting the criterion. There is no separate success-rate field, because that would be a second mechanism for the same number.

- `metric` (string, required) — Metric key, '\<metric>.\<output\_key>'. Keys ending in '.pass' are pass criteria.
- `reduction` (string, required) — How the per-design values were combined.
- `value` (double, required) — Reduced value.
- `n` (integer, required) — Designs that contributed. Below the design count when a metric did not apply to all of them: a pass criterion whose inputs were missing is indeterminate, not a failure, so it is excluded from the denominator rather than counted as zero.

### ErrorBody

Machine-readable error payload.

- `code` (enum, required) — Stable error code, safe to branch on.
  - Allowed values: `schema_violation`, `invalid_request`, `invalid_input`, `request_too_large`, `out_of_memory`, `model_unavailable`, `pipeline_unavailable`, `oracle_unavailable`, `service_busy`, `client_gone`, `timeout`, `internal_error`
- `message` (string, required) — Human-readable explanation.
- `details` (list of string, optional) — Field-level or upstream diagnostics.

### InlineFile

A structure file carried inside the request body.

- `filename` (string, required) — Name the spec refers to, e.g. 'target.cif'. Must be a bare name, not a path.
- `content` (string, required) — UTF-8 mmCIF. PDB is not accepted; see the error it raises.

### RewardOverride

A partial reward spec taking effect at one search checkpoint. Each field an override names **replaces** the base one outright; fields it omits are inherited. An override that switches ``reward_metrics_tags`` must restate the weights that go with the new metrics, because a weight whose metric no longer fires scores ``-inf`` and the search raises rather than pruning on nothing.

- `weights` (map from string to double, optional, nullable) — Replaces the base weights at this checkpoint.
- `clip_values` (map from string to map from string to double, optional) — Replaces the base clip_values at this checkpoint.
- `reward_metrics_tags` (list of enum, optional, nullable) — Replaces the base reward_metrics_tags at this checkpoint.
  - Allowed values: `design`, `hotspot_conditioning`, `rasa_conditioning`, `centroid_conditioning`, `interchain_interactions`, `3d_coordinate_conditioning`, `internal_coordinate_conditioning`, `unindexed`, `partial_diffusion`, `small_molecule_only`, `no_ligand`, `cms`, `cath`, `structure_prediction`, `developability`, `unconditional_refolding`, `ppi_refolding`, `antibody`, `motif_scaffold_refolding`, `internal_coordinate_motif_scaffold_refolding`, `sm_binder_refolding`, `dna_refolding`, `apo_refolding`, `ame_refolding`, `ame_no_ligand_refolding`, `disco_refolding`

### RuntimeLimits

What this deployment refuses, so a 413 is never a mystery.

- `max_tokens` (integer, required) — Tokens in one design.
- `max_num_steps` (integer, required) — Integration steps, when a request pins them.
- `max_request_bytes` (integer, required) — Whole request body.
- `max_search_rollouts` (integer, required) — Trajectories one search may roll out.
- `max_trunk_passes` (integer, optional, nullable) — Trunk evaluations across one trajectory, when a request pins its schedule. Absent from responses of servers that predate the cap.

### DesignDiagnostics

Per-design counters and timings.

- `num_tokens` (integer, required) — Tokens in the design, padding excluded.
- `num_designed_residues` (integer, required) — Tokens the autoencoder decoded into a residue identity.
- `all_coordinates_finite` (boolean, required) — False means the design is unusable; treat as a failed replicate.
- `duration_ms` (double, required) — Wall time for this design: featurization, rollout, decode, and export.
- `num_atomized_tokens` (integer, optional, default: 0) — Atomized ligand atoms carried through the rollout.
- `num_unindexed_insertions` (integer, optional, default: 0) — Unindexed motif tokens the insertion head placed into the design.
- `num_fixed_coordinate_atoms` (integer, optional, default: 0) — Atoms restored from absolute coordinate conditions.
- `batch_size` (integer, optional, default: 1) — Replicates evaluated in the forward pass that produced this design, which is what its seed has to be replayed at. Usually sampling.batch_size, but the last batch of a replicate count that is not a multiple of it is smaller, and its designs belong to that smaller batch.
- `input_ca_rmsd_angstrom` (double, optional, nullable) — CA RMSD to the input backbone. Populated for partial_diffusion and inverse_folding whenever metrics.tags is non-empty (those two tasks add the 'partial_diffusion' metric tag automatically); null if no metrics were requested, or if the design and input CA counts differ, e.g. after an insertion.
- `sequence_recovery` (double, optional, nullable) — Fraction of input residues reproduced. Populated for partial_diffusion and inverse_folding whenever metrics.tags is non-empty, for the same reason as input_ca_rmsd_angstrom; null under the same conditions.

### StructureFile

A design's coordinates.

- `format` ("mmcif", required) — Encoding of 'content'.
- `filename` (string, required) — Suggested file name.
- `content` (string, required) — UTF-8 annotated mmCIF. Provenance columns (annotation_src-component_1_atom, mapped_to_coordinate_conditioned_region, is_unindexed_insertion) map each atom back to the input spec; the designed chain is renumbered from scratch, so they are the only way to find a conditioned motif again.

### DesignRecordMetrics

- double
- integer
- boolean
- string

## Examples

**Request**

```json
{
  "task": "generation",
  "input": {
    "file": {
      "content": "string",
      "filename": "string"
    },
    "format": "string"
  }
}
```

**Response**

```json
{
  "request_id": "string",
  "task": "generation",
  "model": {
    "model_name": "string",
    "checkpoint": "string",
    "autoencoder_checkpoint": "string",
    "device": "string",
    "dtype": "string",
    "num_residue_types": 1,
    "package_version": "string",
    "execution_backend": "bioir",
    "oracle": [
      "oracle_my_predictor"
    ]
  },
  "runtime": {
    "nim_version": "1.0.0",
    "packages": {
      "bionemo_ir": "0.6.0.dev0+cu132"
    },
    "limits": {
      "max_tokens": 1,
      "max_num_steps": 1,
      "max_request_bytes": 1,
      "max_search_rollouts": 1,
      "max_trunk_passes": 1
    },
    "nimtools_version": "string",
    "inference_precision": "string",
    "bioir_dtype": "string",
    "cuda": "string",
    "gpu": "string",
    "gpu_count": 0,
    "gpu_ids": [
      1
    ],
    "compile_lengths": [
      1
    ],
    "cuda_graphs": false,
    "cuda_graph_cache": {},
    "cuda_graph_max_tokens": 0,
    "cuda_graph_slots": 0
  },
  "schedule": {
    "kind": "full",
    "num_steps": 1,
    "backbone_schedule": "string",
    "latent_schedule": "string",
    "recycle_strategy": "string",
    "recycle_schedule": [
      [
        "string"
      ]
    ],
    "recycle_depth": 0,
    "trunk_passes": 1,
    "start_times": {}
  },
  "designs": [
    {
      "design_id": "SAM_hbonds_bsc1_2",
      "replicate_index": 1,
      "diagnostics": {
        "num_tokens": 1,
        "num_designed_residues": 1,
        "all_coordinates_finite": true,
        "duration_ms": 1.1,
        "num_atomized_tokens": 0,
        "num_unindexed_insertions": 0,
        "num_fixed_coordinate_atoms": 0,
        "batch_size": 1,
        "input_ca_rmsd_angstrom": 1.1,
        "sequence_recovery": 1.1
      },
      "origin": "sample",
      "seed": 1,
      "sequence": "string",
      "structure": {
        "format": "string",
        "filename": "string",
        "content": "string"
      },
      "search_reward": 1.1,
      "chain_of_interest": "B_1",
      "metrics": {
        "clash_metrics.frac_atoms_clashing_1p5A": 0.0024,
        "hotspot_obedience.hotspot_obedience": 0.6667,
        "interchain_interactions.hbond_atom_pair_count_coi": 7,
        "sequence_adherence.sequence_adherence": 1
      },
      "runtime_metrics": {
        "metrics_time_s": 0.194,
        "model_forward_time_s": 6.083,
        "postprocess_time_s": 0.087,
        "preprocess_time_s": 0.412,
        "total_time_s": 6.792
      }
    }
  ],
  "duration_ms": 1.1,
  "search": {
    "step_checkpoints": [
      1
    ],
    "n_branch": 1,
    "beam_width": 1,
    "rollouts": 1,
    "reward_keys": [
      "string"
    ],
    "best_reward": 1.1,
    "intermediates_kept": 0,
    "completion_rollouts": 0
  },
  "aggregated_metrics": [
    {
      "metric": "unconditional.pass",
      "reduction": "mean",
      "value": 1.1,
      "n": 1
    }
  ],
  "warnings": [
    "string"
  ]
}
```

**SDK Code**

```python
import requests

url = "https://health.api.nvidia.com/v1/biology/ipd/rfd4-proteina/generative"

payload = {
    "task": "generation",
    "input": {
        "file": {
            "content": "string",
            "filename": "string"
        },
        "format": "string"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://health.api.nvidia.com/v1/biology/ipd/rfd4-proteina/generative';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"task":"generation","input":{"file":{"content":"string","filename":"string"},"format":"string"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://health.api.nvidia.com/v1/biology/ipd/rfd4-proteina/generative"

	payload := strings.NewReader("{\n  \"task\": \"generation\",\n  \"input\": {\n    \"file\": {\n      \"content\": \"string\",\n      \"filename\": \"string\"\n    },\n    \"format\": \"string\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://health.api.nvidia.com/v1/biology/ipd/rfd4-proteina/generative")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"task\": \"generation\",\n  \"input\": {\n    \"file\": {\n      \"content\": \"string\",\n      \"filename\": \"string\"\n    },\n    \"format\": \"string\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://health.api.nvidia.com/v1/biology/ipd/rfd4-proteina/generative")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"task\": \"generation\",\n  \"input\": {\n    \"file\": {\n      \"content\": \"string\",\n      \"filename\": \"string\"\n    },\n    \"format\": \"string\"\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://health.api.nvidia.com/v1/biology/ipd/rfd4-proteina/generative', [
  'body' => '{
  "task": "generation",
  "input": {
    "file": {
      "content": "string",
      "filename": "string"
    },
    "format": "string"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://health.api.nvidia.com/v1/biology/ipd/rfd4-proteina/generative");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"task\": \"generation\",\n  \"input\": {\n    \"file\": {\n      \"content\": \"string\",\n      \"filename\": \"string\"\n    },\n    \"format\": \"string\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "task": "generation",
  "input": [
    "file": [
      "content": "string",
      "filename": "string"
    ],
    "format": "string"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://health.api.nvidia.com/v1/biology/ipd/rfd4-proteina/generative")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```