--- title: Core Concepts | Boltz API Docs description: Key concepts for working with the Boltz API, covering entities, metrics, binding, file inputs, constraints, modifications, and bonds. --- ## Entities and chain IDs Molecular systems are described as a list of entities. Every entity has a `type` and one or more `chain_ids`; sequence and ligand entities use `value`, while glycans use an explicit residue graph. The supported entity types are: - **Protein**: Amino acid sequence (single-letter codes) in the `value` field. Supports `modifications` and `cyclic` options. - **RNA**: Ribonucleotide sequence in the `value` field. - **DNA**: Deoxyribonucleotide sequence in the `value` field. - **Ligand (SMILES)**: Small molecule defined by a SMILES string in the `value` field. - **Ligand (CCD)**: Small molecule defined by one CCD code in the `value` field. `value` is always a string; do not join multiple CCD codes with underscores. - **Glycan**: One or more CCD monosaccharide residues in `residues`, identified by request-local `id` values, with internal covalent connectivity in `bonds`. A single-residue glycan has an empty `bonds` array. Chain IDs are used throughout the API to reference specific chains in constraints, bonds, binding configuration, and results. For a glycan, residue IDs are local to the request and are the stable references used by both internal bonds and external `ccd_atom` references. Multiple `chain_ids` on one glycan entity create identical copies of the same residue graph. ## Metrics The API returns several confidence and quality metrics with prediction and screening results: | Metric | What it measures | | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **pTM** (predicted TM-score) | Global predicted fold quality for the complex (0–1, higher is better). For single-chain inputs, pTM (not ipTM) drives the confidence ranking. | | **ipTM** (interface predicted TM-score) | Confidence in the relative positioning of chains across interfaces (0–1, higher is better). Variants `protein_iptm` and `ligand_iptm` restrict to protein–protein and protein–ligand interfaces. | | **pLDDT** (predicted Local Distance Difference Test) | Per-residue confidence in the local structure, as normalized 0–1 floats (higher is better): `complex_plddt` averaged over the complex and `complex_iplddt` with interface residues up-weighted. | | **PAE** (Predicted Aligned Error) | Expected positional error between residue pairs, in ångström (lower is better), when the structure is aligned on one residue’s frame. For protein-binder designs the minimum at the binder–target interface is surfaced as `min_interaction_pae`. | | **PDE** (Predicted Distance Error) | Expected error in the distance between residue pairs, in ångström (lower is better). Reported as `complex_pde` across the complex and `complex_ipde` at the interface. | | **Structure confidence** | Measures the confidence of the predicted structure (0 = low, 1 = high). It is a composite (≈ 0.8 × `complex_plddt` + 0.2 × ipTM; pTM for single chains) that also orders the returned samples. Usually high, so use it as a quality/sanity filter rather than the primary ranking key. | | **Binding confidence** | Confidence that protein binding occurs, combining affinity probability with structural quality (0–1). For triage, 0.7+ is typically the high-confidence range (computed when binding is requested). | | **Optimization score** | Ranks relative binding strength for lead optimization, normalized 0–1 (higher is better). Use it to prioritize the top-scoring candidates within the same run rather than as a universal pass/fail threshold (computed when binding is requested). | ## Binding Binding configuration tells the model to compute binding metrics for the prediction. There are two binding types: - **Ligand-protein binding** (`ligand_protein_binding`): Specify a `binder_chain_id` pointing to a ligand chain. The ligand must have exactly one copy (single chain ID) and the complex must contain only ligands and proteins. - **Protein-protein binding** (`protein_protein_binding`): Specify `binder_chain_ids` pointing to one or more protein chains. When binding is provided, the prediction output includes binding metrics (`binding_confidence` and `optimization_score`) in addition to structural results. A glycan chain cannot be selected as a ligand-protein or protein-protein binding binder. Glycan-containing complexes can still be submitted for structure prediction without glycan affinity metrics. ## File inputs The API accepts file inputs in two formats: - **URL**: Provide a publicly accessible URL to the file. - **Base64**: Provide the file contents as a Base64-encoded string, along with a `media_type` (e.g., `chemical/x-cif`). ## Constraints Constraints guide predictions by specifying spatial relationships. There are two constraint types: - **Pocket constraints**: Define a binding pocket by specifying a `binder_chain_id` and `contact_residues` (a mapping of chain IDs to arrays of 0-based residue indices). Includes a `max_distance_angstrom` parameter. - **Contact constraints**: Require two tokens to be within a maximum distance. Tokens can be: - `polymer_contact`: Identifies a residue on a polymer chain (chain ID + residue index). - `ligand_contact`: Identifies an atom on a ligand chain (chain ID + atom name). All residue indices in constraints are 0-indexed. Contact tokens cannot reference glycan chains, and a pocket constraint cannot include a glycan chain in `contact_residues`. The current contact schema has no glycan `residue_id` field, so it cannot identify one residue in a glycan graph losslessly. ## Modifications Modifications can be applied to residues in protein, RNA, and DNA entities: - **CCD modifications**: Reference a modification by its CCD code at a specific residue index. SMILES-based custom residue modifications are not currently supported. ## Bonds Bonds are separate from constraints and define covalent bonds between specific atoms. The atom-reference shape depends on the entity: - `polymer_atom`: `chain_id`, 0-based `residue_index`, and `atom_name` for a protein, RNA, or DNA atom. - `ccd_atom`: `chain_id`, glycan `residue_id`, and CCD `atom_id` for a specific monosaccharide residue. - `smiles_atom`: `chain_id` and the numeric `atom_map` from an explicitly atom-mapped SMILES string. - `ligand_atom`: `chain_id` and `atom_name` for a single-residue ligand. New mapped-SMILES bonds should use `smiles_atom`. Keep internal glycosidic bonds inside the glycan entity’s `bonds` array, where both endpoints use `residue_id` and `atom_id`. Put protein-glycan attachments and any other cross-entity or cross-chain covalent bonds in the request-level `bonds` array, using `ccd_atom` for the glycan endpoint.