# Protein

# Design

## Start

**post** `/compute/v1/protein/design`

Create a new design run that generates novel protein binder candidates

### Body Parameters

- `binder_specification: object { chain_selection, modality, structure, 2 more }  or object { entities, modality, type, 2 more }  or object { binder, type, rules }`

  Binder specification for protein design. Use no_template for sequence-defined binders, structure_template for uploaded binder structures, or boltz_curated for Boltz-managed nanobody and antibody defaults.

  - `StructureTemplateBinderSpec = object { chain_selection, modality, structure, 2 more }`

    Binder specification starting from an existing 3D structure. Upload a CIF/PDB file and select which chains to include, which residues to keep, and which regions to redesign. Only chains included in chain_selection are part of the engine run.

    - `chain_selection: map[object { chain_type, crop_residues, design_motifs }  or object { chain_type } ]`

      Chains selected from the uploaded binder structure, keyed by chain ID. Only chains listed here are included in the engine run — any chains omitted from this mapping are ignored. Each value defines which residues to keep (crop_residues). Omit design_motifs to include the chain as fixed scaffold context.

      - `StructureTemplatePolymerChainSpec = object { chain_type, crop_residues, design_motifs }`

        Per-chain crop and design specification for a polymer chain in structure_template mode.

        - `chain_type: "polymer"`

          - `"polymer"`

        - `crop_residues: array of number or "all"`

          0-indexed residue indices to retain from this chain, or 'all' to keep all residues. Residues not listed are removed before design.

          - `UnionMember0 = array of number`

          - `UnionMember1 = "all"`

            - `"all"`

        - `design_motifs: optional array of object { design_length_range, end_index, start_index, type }  or object { after_residue_index, design_length_range, type }`

          Optional motifs (replacement or insertion) defining which regions to redesign on this chain. Omit this field to include the chain as fixed scaffold context.

          - `ReplacementMotif = object { design_length_range, end_index, start_index, type }`

            Replace a contiguous region of the sequence with a designed segment. Residues from start_index to end_index (inclusive) are replaced with a new sequence of the specified length.

            - `design_length_range: object { max, min }`

              Allowed sequence length range for designed regions

              - `max: number`

                Maximum sequence length in residues. Must be >= min.

              - `min: number`

                Minimum sequence length in residues

            - `end_index: number`

              0-indexed end residue (inclusive)

            - `start_index: number`

              0-indexed start residue (inclusive)

            - `type: "replacement"`

              - `"replacement"`

          - `InsertionMotif = object { after_residue_index, design_length_range, type }`

            Insert a designed segment at a specific position in the sequence.

            - `after_residue_index: number`

              0-indexed position after which to insert. Use -1 to insert before the first residue.

            - `design_length_range: object { max, min }`

              Allowed sequence length range for designed regions

              - `max: number`

                Maximum sequence length in residues. Must be >= min.

              - `min: number`

                Minimum sequence length in residues

            - `type: "insertion"`

              - `"insertion"`

      - `StructureTemplateLigandChainSpec = object { chain_type }`

        Per-chain specification for a ligand chain in structure_template mode. The full ligand is always included.

        - `chain_type: "ligand"`

          - `"ligand"`

    - `modality: "peptide" or "antibody" or "nanobody" or "custom_protein"`

      - `"peptide"`

      - `"antibody"`

      - `"nanobody"`

      - `"custom_protein"`

    - `structure: object { type, url }  or object { data, media_type, type }`

      How to provide a CIF structure file. URLs are auto-detected; base64 uploads must use chemical/x-cif media type.

      - `URLSource = object { type, url }`

        - `type: "url"`

          - `"url"`

        - `url: string`

      - `CifBase64Source = object { data, media_type, type }`

        - `data: string`

          Base64-encoded CIF file contents

        - `media_type: "chemical/x-cif"`

          Must be chemical/x-cif for CIF files

          - `"chemical/x-cif"`

        - `type: "base64"`

          - `"base64"`

    - `type: "structure_template"`

      - `"structure_template"`

    - `rules: optional object { excluded_amino_acids, excluded_sequence_motifs, max_hydrophobic_fraction }`

      Constraints applied during sequence design

      - `excluded_amino_acids: optional array of string`

        Single-letter amino acid codes to exclude from design (e.g. ['C', 'P'] to exclude cysteine and proline)

      - `excluded_sequence_motifs: optional array of string`

        Sequence motifs to exclude from designed regions. Designs containing any of these motifs are filtered out before scoring. Use X as a single-residue wildcard (e.g. "NGS", "NXS").

      - `max_hydrophobic_fraction: optional number`

        Maximum allowed fraction of hydrophobic residues (I, L, V, M, F, W) in designed regions. Designs exceeding this threshold are filtered out before scoring. Leave empty to disable.

  - `NoTemplateBinderSpec = object { entities, modality, type, 2 more }`

    Binder specification without a structural template. Define the binder from sequence components (fixed and designed segments) without providing a starting 3D structure.

    - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 3 more`

      Binder entities composing the design. At least one must be a designed_protein entity. Additional fixed entities (RNA, DNA, ligands) can be included as part of the complex.

      - `DesignedProteinEntity = object { chain_ids, type, value, 2 more }`

        Protein binder entity with designed and/or fixed segments.

        - `chain_ids: array of string`

          Chain IDs to assign to this entity

        - `type: "designed_protein"`

          - `"designed_protein"`

        - `value: string`

          Binder sequence specification. Fixed amino acids are written as literal single-letter codes. Designed regions are written as a length (fixed) or a length range (min..max). Example: "MKTAYI5..10VKSHFSRQ" means fixed MKTAYI, then 5-10 designed residues, then fixed VKSHFSRQ. "20" means 20 fully designed residues. "ACDE8GHI" means fixed ACDE, then 8 designed residues, then fixed GHI.

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Optional polymer modifications. Defaults to [] when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `FixedProteinEntity = object { chain_ids, type, value, 2 more }`

        A fixed protein entity whose sequence is not redesigned.

        - `chain_ids: array of string`

          Chain IDs to assign to this entity

        - `type: "protein"`

          - `"protein"`

        - `value: string`

          Amino acid sequence (one-letter codes)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Optional polymer modifications. Defaults to [] when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `FixedRnaEntity = object { chain_ids, type, value, 2 more }`

        - `chain_ids: array of string`

          Chain IDs to assign to this entity

        - `type: "rna"`

          - `"rna"`

        - `value: string`

          RNA nucleotide sequence (A, C, G, U, N)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Optional polymer modifications. Defaults to [] when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `FixedDnaEntity = object { chain_ids, type, value, 2 more }`

        - `chain_ids: array of string`

          Chain IDs to assign to this entity

        - `type: "dna"`

          - `"dna"`

        - `value: string`

          DNA nucleotide sequence (A, C, G, T, N)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Optional polymer modifications. Defaults to [] when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `FixedLigandSmilesEntity = object { chain_ids, type, value }`

        - `chain_ids: array of string`

          Chain IDs to assign to this entity

        - `type: "ligand_smiles"`

          - `"ligand_smiles"`

        - `value: string`

          SMILES string representing the ligand

      - `FixedLigandCcdEntity = object { chain_ids, type, value }`

        - `chain_ids: array of string`

          Chain IDs to assign to this entity

        - `type: "ligand_ccd"`

          - `"ligand_ccd"`

        - `value: string`

          CCD code from RCSB PDB (e.g. 'ATP', 'ADP')

    - `modality: "peptide" or "antibody" or "nanobody" or "custom_protein"`

      - `"peptide"`

      - `"antibody"`

      - `"nanobody"`

      - `"custom_protein"`

    - `type: "no_template"`

      - `"no_template"`

    - `bonds: optional array of object { atom1, atom2 }`

      Covalent bond constraints between atoms in the binder complex. If defining bonds where an atom is part of a designed protein chain, assume residue indices count designed regions as the minimum length. Example: designed protein "1..3C1..2", "C" is residue 1 (0-indexed) of the designed protein.

      - `atom1: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

        Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

        - `LigandAtom = object { atom_name, chain_id, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

          - `chain_id: string`

            Chain ID containing the atom

          - `type: "ligand_atom"`

            - `"ligand_atom"`

        - `PolymerAtom = object { atom_name, chain_id, residue_index, type }`

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB)

          - `chain_id: string`

            Chain ID containing the atom

          - `residue_index: number`

            0-based residue index

          - `type: "polymer_atom"`

            - `"polymer_atom"`

      - `atom2: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

        Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

        - `LigandAtom = object { atom_name, chain_id, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

          - `chain_id: string`

            Chain ID containing the atom

          - `type: "ligand_atom"`

            - `"ligand_atom"`

        - `PolymerAtom = object { atom_name, chain_id, residue_index, type }`

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB)

          - `chain_id: string`

            Chain ID containing the atom

          - `residue_index: number`

            0-based residue index

          - `type: "polymer_atom"`

            - `"polymer_atom"`

    - `rules: optional object { excluded_amino_acids, excluded_sequence_motifs, max_hydrophobic_fraction }`

      Constraints applied during sequence design

      - `excluded_amino_acids: optional array of string`

        Single-letter amino acid codes to exclude from design (e.g. ['C', 'P'] to exclude cysteine and proline)

      - `excluded_sequence_motifs: optional array of string`

        Sequence motifs to exclude from designed regions. Designs containing any of these motifs are filtered out before scoring. Use X as a single-residue wildcard (e.g. "NGS", "NXS").

      - `max_hydrophobic_fraction: optional number`

        Maximum allowed fraction of hydrophobic residues (I, L, V, M, F, W) in designed regions. Designs exceeding this threshold are filtered out before scoring. Leave empty to disable.

  - `BoltzCuratedBinderSpec = object { binder, type, rules }`

    Boltz-managed curated binder specification. Choose a curated nanobody or antibody family and Boltz will select from maintained template lists during design. The curated lists are managed by Boltz and may be updated over time to improve quality and coverage.

    - `binder: "boltz_nanobody" or "boltz_antibody"`

      Boltz-managed curated binder family. Boltz maintains and may update the underlying template lists on behalf of customers.

      - `"boltz_nanobody"`

      - `"boltz_antibody"`

    - `type: "boltz_curated"`

      - `"boltz_curated"`

    - `rules: optional object { excluded_amino_acids, excluded_sequence_motifs, max_hydrophobic_fraction }`

      Constraints applied during sequence design

      - `excluded_amino_acids: optional array of string`

        Single-letter amino acid codes to exclude from design (e.g. ['C', 'P'] to exclude cysteine and proline)

      - `excluded_sequence_motifs: optional array of string`

        Sequence motifs to exclude from designed regions. Designs containing any of these motifs are filtered out before scoring. Use X as a single-residue wildcard (e.g. "NGS", "NXS").

      - `max_hydrophobic_fraction: optional number`

        Maximum allowed fraction of hydrophobic residues (I, L, V, M, F, W) in designed regions. Designs exceeding this threshold are filtered out before scoring. Leave empty to disable.

- `num_proteins: number`

  Number of protein designs to generate. Must be between 10 and 1,000,000.

- `target: object { chain_selection, structure, type }  or object { entities, type, bonds, 3 more }`

  Target specification (structure template or template-free)

  - `StructureTemplateTarget = object { chain_selection, structure, type }`

    Target defined by an uploaded 3D structure (CIF or PDB file). Only chains included in chain_selection are used.

    - `chain_selection: map[object { chain_type, crop_residues, epitope_residues, flexible_residues }  or object { chain_type } ]`

      Chains selected from the uploaded structure, keyed by chain ID. Only chains listed here are included in the engine run — any chains omitted from this mapping are ignored. Each value defines which residues to keep, which are epitope residues, and which are flexible.

      - `StructureTemplateTargetPolymerChainSpec = object { chain_type, crop_residues, epitope_residues, flexible_residues }`

        Per-chain specification for a polymer (protein/RNA/DNA) chain in a structure template target.

        - `chain_type: "polymer"`

          - `"polymer"`

        - `crop_residues: array of number or "all"`

          0-indexed residue indices to retain from this chain, or 'all' to keep all residues. Residues not listed are excluded from the engine run.

          - `UnionMember0 = array of number`

            0-indexed residue indices to keep

          - `UnionMember1 = "all"`

            - `"all"`

        - `epitope_residues: optional array of number`

          0-indexed residue indices where binder contact is desired (the epitope). All indices must be present in crop_residues.

        - `flexible_residues: optional array of number`

          0-indexed residue indices allowed to move during design (e.g. flexible loop regions). All indices must be present in crop_residues.

      - `StructureTemplateTargetLigandChainSpec = object { chain_type }`

        Per-chain specification for a ligand chain in a structure template target. The full ligand is always included.

        - `chain_type: "ligand"`

          - `"ligand"`

    - `structure: object { type, url }  or object { data, media_type, type }`

      How to provide a CIF structure file. URLs are auto-detected; base64 uploads must use chemical/x-cif media type.

      - `URLSource = object { type, url }`

        - `type: "url"`

          - `"url"`

        - `url: string`

      - `CifBase64Source = object { data, media_type, type }`

        - `data: string`

          Base64-encoded CIF file contents

        - `media_type: "chemical/x-cif"`

          Must be chemical/x-cif for CIF files

          - `"chemical/x-cif"`

        - `type: "base64"`

          - `"base64"`

    - `type: "structure_template"`

      - `"structure_template"`

  - `NoTemplateTarget = object { entities, type, bonds, 3 more }`

    Target defined by sequences only, without a 3D structure template

    - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 2 more`

      Entities (proteins, RNA, DNA, ligands) defining the target complex.

      - `ProteinEntity = object { chain_ids, type, value, 2 more }`

        - `chain_ids: array of string`

          Chain IDs for this entity

        - `type: "protein"`

          - `"protein"`

        - `value: string`

          Amino acid sequence (one-letter codes)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Post-translational modifications. Optional; defaults to an empty list when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `RnaEntity = object { chain_ids, type, value, 2 more }`

        - `chain_ids: array of string`

          Chain IDs for this entity

        - `type: "rna"`

          - `"rna"`

        - `value: string`

          RNA nucleotide sequence (A, C, G, U, N)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Chemical modifications. Optional; defaults to an empty list when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `DnaEntity = object { chain_ids, type, value, 2 more }`

        - `chain_ids: array of string`

          Chain IDs for this entity

        - `type: "dna"`

          - `"dna"`

        - `value: string`

          DNA nucleotide sequence (A, C, G, T, N)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Chemical modifications. Optional; defaults to an empty list when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `LigandCcdEntity = object { chain_ids, type, value }`

        - `chain_ids: array of string`

          Chain IDs for this ligand

        - `type: "ligand_ccd"`

          - `"ligand_ccd"`

        - `value: string`

          CCD code (e.g., ATP, ADP)

      - `LigandSmilesEntity = object { chain_ids, type, value }`

        - `chain_ids: array of string`

          Chain IDs for this ligand

        - `type: "ligand_smiles"`

          - `"ligand_smiles"`

        - `value: string`

          SMILES string representing the ligand

    - `type: "no_template"`

      - `"no_template"`

    - `bonds: optional array of object { atom1, atom2 }`

      Covalent bond constraints between atoms in the target complex. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

      - `atom1: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

        Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

        - `LigandAtom = object { atom_name, chain_id, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

          - `chain_id: string`

            Chain ID containing the atom

          - `type: "ligand_atom"`

            - `"ligand_atom"`

        - `PolymerAtom = object { atom_name, chain_id, residue_index, type }`

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB)

          - `chain_id: string`

            Chain ID containing the atom

          - `residue_index: number`

            0-based residue index

          - `type: "polymer_atom"`

            - `"polymer_atom"`

      - `atom2: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

        Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

        - `LigandAtom = object { atom_name, chain_id, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

          - `chain_id: string`

            Chain ID containing the atom

          - `type: "ligand_atom"`

            - `"ligand_atom"`

        - `PolymerAtom = object { atom_name, chain_id, residue_index, type }`

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB)

          - `chain_id: string`

            Chain ID containing the atom

          - `residue_index: number`

            0-based residue index

          - `type: "polymer_atom"`

            - `"polymer_atom"`

    - `constraints: optional array of object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }  or object { max_distance_angstrom, token1, token2, 2 more }`

      Structural constraints (pocket and contact). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

      - `PocketConstraint = object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }`

        Constrains the binder to interact with specific pocket residues on the target.

        - `binder_chain_id: string`

          Chain ID of the binder molecule

        - `contact_residues: map[array of number]`

          Binding pocket residues keyed by chain ID. Each key is a chain ID (e.g. "A") and the value is an array of 0-indexed residue indices that define the pocket on that chain.

        - `max_distance_angstrom: number`

          Maximum allowed distance in Angstroms between binder and pocket residues. Typical range: 4-8 A.

        - `type: "pocket"`

          - `"pocket"`

        - `force: optional boolean`

          Whether to force the constraint

      - `ContactConstraint = object { max_distance_angstrom, token1, token2, 2 more }`

        Contact constraint between two tokens. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

        - `max_distance_angstrom: number`

          Maximum distance in Angstroms

        - `token1: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

          Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `PolymerContactToken = object { chain_id, residue_index, type }`

            - `chain_id: string`

              Chain ID

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_contact"`

              - `"polymer_contact"`

          - `LigandContactToken = object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID

            - `type: "ligand_contact"`

              - `"ligand_contact"`

        - `token2: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

          Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `PolymerContactToken = object { chain_id, residue_index, type }`

            - `chain_id: string`

              Chain ID

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_contact"`

              - `"polymer_contact"`

          - `LigandContactToken = object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID

            - `type: "ligand_contact"`

              - `"ligand_contact"`

        - `type: "contact"`

          - `"contact"`

        - `force: optional boolean`

          Whether to force the constraint

    - `epitope_ligand_chains: optional array of string`

      Chain IDs of ligand entities that are part of the binding epitope. Ligands are marked as epitope in full (no residue-level selection).

    - `epitope_residues: optional map[array of number]`

      Polymer chain residues where binder contact is desired (the epitope). Each key is a chain ID of a polymer entity, each value is an array of 0-indexed residue indices.

- `idempotency_key: optional string`

  Client-provided key to prevent duplicate submissions on retries

- `workspace_id: optional string`

  Target workspace ID (admin keys only; ignored for workspace keys)

### Returns

- `id: string`

  Unique ProteinDesignRun identifier

- `completed_at: string`

- `created_at: string`

- `data_deleted_at: string`

  When the input, output, and result data was permanently deleted. Null if data has not been deleted.

- `engine: "boltz-protein-design"`

  Engine used for protein design

  - `"boltz-protein-design"`

- `engine_version: string`

  Engine version used for protein design

- `error: object { code, message, details }`

  - `code: string`

    Machine-readable error code

  - `message: string`

    Human-readable error message

  - `details: optional unknown`

    Additional field-level error details keyed by input path, when available.

- `input: object { binder_specification, num_proteins, target, 2 more }`

  Pipeline input (null if data deleted)

  - `binder_specification: object { chain_selection, modality, structure, 2 more }  or object { entities, modality, type, 2 more }  or object { binder, type, rules }`

    Binder specification for protein design. Use no_template for sequence-defined binders, structure_template for uploaded binder structures, or boltz_curated for Boltz-managed nanobody and antibody defaults.

    - `StructureTemplateBinderSpecResponse = object { chain_selection, modality, structure, 2 more }`

      Binder specification starting from an existing 3D structure. Upload a CIF/PDB file and select which chains to include, which residues to keep, and which regions to redesign. Only chains included in chain_selection are part of the engine run.

      - `chain_selection: map[object { chain_type, crop_residues, design_motifs }  or object { chain_type } ]`

        Chains selected from the uploaded binder structure, keyed by chain ID. Only chains listed here are included in the engine run — any chains omitted from this mapping are ignored. Each value defines which residues to keep (crop_residues). Omit design_motifs to include the chain as fixed scaffold context.

        - `StructureTemplatePolymerChainSpec = object { chain_type, crop_residues, design_motifs }`

          Per-chain crop and design specification for a polymer chain in structure_template mode.

          - `chain_type: "polymer"`

            - `"polymer"`

          - `crop_residues: array of number or "all"`

            0-indexed residue indices to retain from this chain, or 'all' to keep all residues. Residues not listed are removed before design.

            - `UnionMember0 = array of number`

            - `UnionMember1 = "all"`

              - `"all"`

          - `design_motifs: optional array of object { design_length_range, end_index, start_index, type }  or object { after_residue_index, design_length_range, type }`

            Optional motifs (replacement or insertion) defining which regions to redesign on this chain. Omit this field to include the chain as fixed scaffold context.

            - `ReplacementMotif = object { design_length_range, end_index, start_index, type }`

              Replace a contiguous region of the sequence with a designed segment. Residues from start_index to end_index (inclusive) are replaced with a new sequence of the specified length.

              - `design_length_range: object { max, min }`

                Allowed sequence length range for designed regions

                - `max: number`

                  Maximum sequence length in residues. Must be >= min.

                - `min: number`

                  Minimum sequence length in residues

              - `end_index: number`

                0-indexed end residue (inclusive)

              - `start_index: number`

                0-indexed start residue (inclusive)

              - `type: "replacement"`

                - `"replacement"`

            - `InsertionMotif = object { after_residue_index, design_length_range, type }`

              Insert a designed segment at a specific position in the sequence.

              - `after_residue_index: number`

                0-indexed position after which to insert. Use -1 to insert before the first residue.

              - `design_length_range: object { max, min }`

                Allowed sequence length range for designed regions

                - `max: number`

                  Maximum sequence length in residues. Must be >= min.

                - `min: number`

                  Minimum sequence length in residues

              - `type: "insertion"`

                - `"insertion"`

        - `StructureTemplateLigandChainSpec = object { chain_type }`

          Per-chain specification for a ligand chain in structure_template mode. The full ligand is always included.

          - `chain_type: "ligand"`

            - `"ligand"`

      - `modality: "peptide" or "antibody" or "nanobody" or "custom_protein"`

        - `"peptide"`

        - `"antibody"`

        - `"nanobody"`

        - `"custom_protein"`

      - `structure: object { url, url_expires_at }`

        - `url: string`

          URL to download the file

        - `url_expires_at: string`

          When the presigned URL expires

      - `type: "structure_template"`

        - `"structure_template"`

      - `rules: optional object { excluded_amino_acids, excluded_sequence_motifs, max_hydrophobic_fraction }`

        Constraints applied during sequence design

        - `excluded_amino_acids: optional array of string`

          Single-letter amino acid codes to exclude from design (e.g. ['C', 'P'] to exclude cysteine and proline)

        - `excluded_sequence_motifs: optional array of string`

          Sequence motifs to exclude from designed regions. Designs containing any of these motifs are filtered out before scoring. Use X as a single-residue wildcard (e.g. "NGS", "NXS").

        - `max_hydrophobic_fraction: optional number`

          Maximum allowed fraction of hydrophobic residues (I, L, V, M, F, W) in designed regions. Designs exceeding this threshold are filtered out before scoring. Leave empty to disable.

    - `NoTemplateBinderSpecResponse = object { entities, modality, type, 2 more }`

      Binder specification without a structural template. Define the binder from sequence components (fixed and designed segments) without providing a starting 3D structure.

      - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 3 more`

        Binder entities composing the design. At least one must be a designed_protein entity. Additional fixed entities (RNA, DNA, ligands) can be included as part of the complex.

        - `DesignedProteinEntityResponse = object { chain_ids, type, value, 2 more }`

          Protein binder entity with designed and/or fixed segments.

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "designed_protein"`

            - `"designed_protein"`

          - `value: string`

            Binder sequence specification. Fixed amino acids are written as literal single-letter codes. Designed regions are written as a length (fixed) or a length range (min..max). Example: "MKTAYI5..10VKSHFSRQ" means fixed MKTAYI, then 5-10 designed residues, then fixed VKSHFSRQ. "20" means 20 fully designed residues. "ACDE8GHI" means fixed ACDE, then 8 designed residues, then fixed GHI.

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Optional polymer modifications. Defaults to [] when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `FixedProteinEntityResponse = object { chain_ids, type, value, 2 more }`

          A fixed protein entity whose sequence is not redesigned.

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "protein"`

            - `"protein"`

          - `value: string`

            Amino acid sequence (one-letter codes)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Optional polymer modifications. Defaults to [] when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `FixedRnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "rna"`

            - `"rna"`

          - `value: string`

            RNA nucleotide sequence (A, C, G, U, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Optional polymer modifications. Defaults to [] when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `FixedDnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "dna"`

            - `"dna"`

          - `value: string`

            DNA nucleotide sequence (A, C, G, T, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Optional polymer modifications. Defaults to [] when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `FixedLigandSmilesEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "ligand_smiles"`

            - `"ligand_smiles"`

          - `value: string`

            SMILES string representing the ligand

        - `FixedLigandCcdEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "ligand_ccd"`

            - `"ligand_ccd"`

          - `value: string`

            CCD code from RCSB PDB (e.g. 'ATP', 'ADP')

      - `modality: "peptide" or "antibody" or "nanobody" or "custom_protein"`

        - `"peptide"`

        - `"antibody"`

        - `"nanobody"`

        - `"custom_protein"`

      - `type: "no_template"`

        - `"no_template"`

      - `bonds: optional array of object { atom1, atom2 }`

        Covalent bond constraints between atoms in the binder complex. If defining bonds where an atom is part of a designed protein chain, assume residue indices count designed regions as the minimum length. Example: designed protein "1..3C1..2", "C" is residue 1 (0-indexed) of the designed protein.

        - `atom1: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

        - `atom2: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

      - `rules: optional object { excluded_amino_acids, excluded_sequence_motifs, max_hydrophobic_fraction }`

        Constraints applied during sequence design

        - `excluded_amino_acids: optional array of string`

          Single-letter amino acid codes to exclude from design (e.g. ['C', 'P'] to exclude cysteine and proline)

        - `excluded_sequence_motifs: optional array of string`

          Sequence motifs to exclude from designed regions. Designs containing any of these motifs are filtered out before scoring. Use X as a single-residue wildcard (e.g. "NGS", "NXS").

        - `max_hydrophobic_fraction: optional number`

          Maximum allowed fraction of hydrophobic residues (I, L, V, M, F, W) in designed regions. Designs exceeding this threshold are filtered out before scoring. Leave empty to disable.

    - `BoltzCuratedBinderSpecResponse = object { binder, type, rules }`

      Boltz-managed curated binder specification. Choose a curated nanobody or antibody family and Boltz will select from maintained template lists during design. The curated lists are managed by Boltz and may be updated over time to improve quality and coverage.

      - `binder: "boltz_nanobody" or "boltz_antibody"`

        Boltz-managed curated binder family. Boltz maintains and may update the underlying template lists on behalf of customers.

        - `"boltz_nanobody"`

        - `"boltz_antibody"`

      - `type: "boltz_curated"`

        - `"boltz_curated"`

      - `rules: optional object { excluded_amino_acids, excluded_sequence_motifs, max_hydrophobic_fraction }`

        Constraints applied during sequence design

        - `excluded_amino_acids: optional array of string`

          Single-letter amino acid codes to exclude from design (e.g. ['C', 'P'] to exclude cysteine and proline)

        - `excluded_sequence_motifs: optional array of string`

          Sequence motifs to exclude from designed regions. Designs containing any of these motifs are filtered out before scoring. Use X as a single-residue wildcard (e.g. "NGS", "NXS").

        - `max_hydrophobic_fraction: optional number`

          Maximum allowed fraction of hydrophobic residues (I, L, V, M, F, W) in designed regions. Designs exceeding this threshold are filtered out before scoring. Leave empty to disable.

  - `num_proteins: number`

    Number of protein designs to generate. Must be between 10 and 1,000,000.

  - `target: object { chain_selection, structure, type }  or object { entities, type, bonds, 3 more }`

    Target specification (structure template or template-free)

    - `StructureTemplateTargetResponse = object { chain_selection, structure, type }`

      Target defined by an uploaded 3D structure (CIF or PDB file). Only chains included in chain_selection are used.

      - `chain_selection: map[object { chain_type, crop_residues, epitope_residues, flexible_residues }  or object { chain_type } ]`

        Chains selected from the uploaded structure, keyed by chain ID. Only chains listed here are included in the engine run — any chains omitted from this mapping are ignored. Each value defines which residues to keep, which are epitope residues, and which are flexible.

        - `StructureTemplateTargetPolymerChainSpec = object { chain_type, crop_residues, epitope_residues, flexible_residues }`

          Per-chain specification for a polymer (protein/RNA/DNA) chain in a structure template target.

          - `chain_type: "polymer"`

            - `"polymer"`

          - `crop_residues: array of number or "all"`

            0-indexed residue indices to retain from this chain, or 'all' to keep all residues. Residues not listed are excluded from the engine run.

            - `UnionMember0 = array of number`

              0-indexed residue indices to keep

            - `UnionMember1 = "all"`

              - `"all"`

          - `epitope_residues: optional array of number`

            0-indexed residue indices where binder contact is desired (the epitope). All indices must be present in crop_residues.

          - `flexible_residues: optional array of number`

            0-indexed residue indices allowed to move during design (e.g. flexible loop regions). All indices must be present in crop_residues.

        - `StructureTemplateTargetLigandChainSpec = object { chain_type }`

          Per-chain specification for a ligand chain in a structure template target. The full ligand is always included.

          - `chain_type: "ligand"`

            - `"ligand"`

      - `structure: object { url, url_expires_at }`

        - `url: string`

          URL to download the file

        - `url_expires_at: string`

          When the presigned URL expires

      - `type: "structure_template"`

        - `"structure_template"`

    - `NoTemplateTargetResponse = object { entities, type, bonds, 3 more }`

      Target defined by sequences only, without a 3D structure template

      - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 2 more`

        Entities (proteins, RNA, DNA, ligands) defining the target complex.

        - `ProteinEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "protein"`

            - `"protein"`

          - `value: string`

            Amino acid sequence (one-letter codes)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Post-translational modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `RnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "rna"`

            - `"rna"`

          - `value: string`

            RNA nucleotide sequence (A, C, G, U, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Chemical modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `DnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "dna"`

            - `"dna"`

          - `value: string`

            DNA nucleotide sequence (A, C, G, T, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Chemical modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `LigandCcdEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs for this ligand

          - `type: "ligand_ccd"`

            - `"ligand_ccd"`

          - `value: string`

            CCD code (e.g., ATP, ADP)

        - `LigandSmilesEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs for this ligand

          - `type: "ligand_smiles"`

            - `"ligand_smiles"`

          - `value: string`

            SMILES string representing the ligand

      - `type: "no_template"`

        - `"no_template"`

      - `bonds: optional array of object { atom1, atom2 }`

        Covalent bond constraints between atoms in the target complex. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

        - `atom1: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

        - `atom2: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

      - `constraints: optional array of object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }  or object { max_distance_angstrom, token1, token2, 2 more }`

        Structural constraints (pocket and contact). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

        - `PocketConstraintResponse = object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }`

          Constrains the binder to interact with specific pocket residues on the target.

          - `binder_chain_id: string`

            Chain ID of the binder molecule

          - `contact_residues: map[array of number]`

            Binding pocket residues keyed by chain ID. Each key is a chain ID (e.g. "A") and the value is an array of 0-indexed residue indices that define the pocket on that chain.

          - `max_distance_angstrom: number`

            Maximum allowed distance in Angstroms between binder and pocket residues. Typical range: 4-8 A.

          - `type: "pocket"`

            - `"pocket"`

          - `force: optional boolean`

            Whether to force the constraint

        - `ContactConstraintResponse = object { max_distance_angstrom, token1, token2, 2 more }`

          Contact constraint between two tokens. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `max_distance_angstrom: number`

            Maximum distance in Angstroms

          - `token1: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `PolymerContactTokenResponse = object { chain_id, residue_index, type }`

              - `chain_id: string`

                Chain ID

              - `residue_index: number`

                0-based residue index

              - `type: "polymer_contact"`

                - `"polymer_contact"`

            - `LigandContactTokenResponse = object { atom_name, chain_id, type }`

              Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

              - `atom_name: string`

                Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

              - `chain_id: string`

                Chain ID

              - `type: "ligand_contact"`

                - `"ligand_contact"`

          - `token2: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `PolymerContactTokenResponse = object { chain_id, residue_index, type }`

              - `chain_id: string`

                Chain ID

              - `residue_index: number`

                0-based residue index

              - `type: "polymer_contact"`

                - `"polymer_contact"`

            - `LigandContactTokenResponse = object { atom_name, chain_id, type }`

              Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

              - `atom_name: string`

                Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

              - `chain_id: string`

                Chain ID

              - `type: "ligand_contact"`

                - `"ligand_contact"`

          - `type: "contact"`

            - `"contact"`

          - `force: optional boolean`

            Whether to force the constraint

      - `epitope_ligand_chains: optional array of string`

        Chain IDs of ligand entities that are part of the binding epitope. Ligands are marked as epitope in full (no residue-level selection).

      - `epitope_residues: optional map[array of number]`

        Polymer chain residues where binder contact is desired (the epitope). Each key is a chain ID of a polymer entity, each value is an array of 0-indexed residue indices.

  - `idempotency_key: optional string`

    Client-provided key to prevent duplicate submissions on retries

  - `workspace_id: optional string`

    Target workspace ID (admin keys only; ignored for workspace keys)

- `livemode: boolean`

  Whether this resource was created with a live API key.

- `progress: object { num_proteins_generated, total_proteins_to_generate, latest_result_id }`

  - `num_proteins_generated: number`

    Number of protein binders generated so far

  - `total_proteins_to_generate: number`

    Total number of protein binders requested

  - `latest_result_id: optional string`

    ID of the most recently generated result

- `started_at: string`

- `status: "pending" or "running" or "succeeded" or 2 more`

  - `"pending"`

  - `"running"`

  - `"succeeded"`

  - `"failed"`

  - `"stopped"`

- `stopped_at: string`

- `workspace_id: string`

  Workspace ID

- `idempotency_key: optional string`

  Client-provided idempotency key

### Example

```http
curl https://api.boltz.bio/compute/v1/protein/design \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $BOLTZ_API_KEY" \
    -d '{
          "binder_specification": {
            "chain_selection": {
              "B": {
                "chain_type": "polymer",
                "crop_residues": [
                  0,
                  1,
                  2,
                  3,
                  4,
                  5,
                  6,
                  7,
                  8,
                  9
                ],
                "design_motifs": [
                  {
                    "design_length_range": {
                      "max": 8,
                      "min": 4
                    },
                    "end_index": 5,
                    "start_index": 0,
                    "type": "replacement"
                  }
                ]
              }
            },
            "modality": "peptide",
            "structure": {
              "type": "url",
              "url": "https://example.com"
            },
            "type": "structure_template"
          },
          "num_proteins": 10,
          "target": {
            "chain_selection": {
              "A": {
                "chain_type": "polymer",
                "crop_residues": [
                  0,
                  1,
                  2,
                  3,
                  4,
                  5,
                  6,
                  7,
                  8,
                  9,
                  10,
                  11,
                  12
                ],
                "epitope_residues": [
                  10,
                  11,
                  12
                ],
                "flexible_residues": [
                  5,
                  6,
                  7
                ]
              }
            },
            "structure": {
              "type": "url",
              "url": "https://example.com"
            },
            "type": "structure_template"
          }
        }'
```

## List

**get** `/compute/v1/protein/design`

List protein design runs, optionally filtered by workspace

### Query Parameters

- `after_id: optional string`

  Return results after this ID

- `before_id: optional string`

  Return results before this ID

- `limit: optional number`

  Max items to return. Defaults to 100.

- `workspace_id: optional string`

  Filter by workspace ID. Only used with admin API keys. If not provided, defaults to the workspace associated with the API key, or the default workspace for admin keys.

### Returns

- `data: array of object { id, completed_at, created_at, 11 more }`

  - `id: string`

    Unique ProteinDesignRunSummary identifier

  - `completed_at: string`

  - `created_at: string`

  - `data_deleted_at: string`

    When the input, output, and result data was permanently deleted. Null if data has not been deleted.

  - `engine: "boltz-protein-design"`

    Engine used for protein design

    - `"boltz-protein-design"`

  - `engine_version: string`

    Engine version used for protein design

  - `error: object { code, message, details }`

    - `code: string`

      Machine-readable error code

    - `message: string`

      Human-readable error message

    - `details: optional unknown`

      Additional field-level error details keyed by input path, when available.

  - `livemode: boolean`

    Whether this resource was created with a live API key.

  - `progress: object { num_proteins_generated, total_proteins_to_generate, latest_result_id }`

    - `num_proteins_generated: number`

      Number of protein binders generated so far

    - `total_proteins_to_generate: number`

      Total number of protein binders requested

    - `latest_result_id: optional string`

      ID of the most recently generated result

  - `started_at: string`

  - `status: "pending" or "running" or "succeeded" or 2 more`

    - `"pending"`

    - `"running"`

    - `"succeeded"`

    - `"failed"`

    - `"stopped"`

  - `stopped_at: string`

  - `workspace_id: string`

    Workspace ID

  - `idempotency_key: optional string`

    Client-provided idempotency key

- `first_id: string`

  ID of the first item. Use as before_id for the previous page.

- `has_more: boolean`

- `last_id: string`

  ID of the last item. Use as after_id for the next page.

### Example

```http
curl https://api.boltz.bio/compute/v1/protein/design \
    -H "x-api-key: $BOLTZ_API_KEY"
```

## Retrieve

**get** `/compute/v1/protein/design/{id}`

Retrieve a design run by ID, including progress and status

### Path Parameters

- `id: string`

### Query Parameters

- `workspace_id: optional string`

  Workspace ID. Only used with admin API keys. Ignored (or validated) for workspace-scoped keys.

### Returns

- `id: string`

  Unique ProteinDesignRun identifier

- `completed_at: string`

- `created_at: string`

- `data_deleted_at: string`

  When the input, output, and result data was permanently deleted. Null if data has not been deleted.

- `engine: "boltz-protein-design"`

  Engine used for protein design

  - `"boltz-protein-design"`

- `engine_version: string`

  Engine version used for protein design

- `error: object { code, message, details }`

  - `code: string`

    Machine-readable error code

  - `message: string`

    Human-readable error message

  - `details: optional unknown`

    Additional field-level error details keyed by input path, when available.

- `input: object { binder_specification, num_proteins, target, 2 more }`

  Pipeline input (null if data deleted)

  - `binder_specification: object { chain_selection, modality, structure, 2 more }  or object { entities, modality, type, 2 more }  or object { binder, type, rules }`

    Binder specification for protein design. Use no_template for sequence-defined binders, structure_template for uploaded binder structures, or boltz_curated for Boltz-managed nanobody and antibody defaults.

    - `StructureTemplateBinderSpecResponse = object { chain_selection, modality, structure, 2 more }`

      Binder specification starting from an existing 3D structure. Upload a CIF/PDB file and select which chains to include, which residues to keep, and which regions to redesign. Only chains included in chain_selection are part of the engine run.

      - `chain_selection: map[object { chain_type, crop_residues, design_motifs }  or object { chain_type } ]`

        Chains selected from the uploaded binder structure, keyed by chain ID. Only chains listed here are included in the engine run — any chains omitted from this mapping are ignored. Each value defines which residues to keep (crop_residues). Omit design_motifs to include the chain as fixed scaffold context.

        - `StructureTemplatePolymerChainSpec = object { chain_type, crop_residues, design_motifs }`

          Per-chain crop and design specification for a polymer chain in structure_template mode.

          - `chain_type: "polymer"`

            - `"polymer"`

          - `crop_residues: array of number or "all"`

            0-indexed residue indices to retain from this chain, or 'all' to keep all residues. Residues not listed are removed before design.

            - `UnionMember0 = array of number`

            - `UnionMember1 = "all"`

              - `"all"`

          - `design_motifs: optional array of object { design_length_range, end_index, start_index, type }  or object { after_residue_index, design_length_range, type }`

            Optional motifs (replacement or insertion) defining which regions to redesign on this chain. Omit this field to include the chain as fixed scaffold context.

            - `ReplacementMotif = object { design_length_range, end_index, start_index, type }`

              Replace a contiguous region of the sequence with a designed segment. Residues from start_index to end_index (inclusive) are replaced with a new sequence of the specified length.

              - `design_length_range: object { max, min }`

                Allowed sequence length range for designed regions

                - `max: number`

                  Maximum sequence length in residues. Must be >= min.

                - `min: number`

                  Minimum sequence length in residues

              - `end_index: number`

                0-indexed end residue (inclusive)

              - `start_index: number`

                0-indexed start residue (inclusive)

              - `type: "replacement"`

                - `"replacement"`

            - `InsertionMotif = object { after_residue_index, design_length_range, type }`

              Insert a designed segment at a specific position in the sequence.

              - `after_residue_index: number`

                0-indexed position after which to insert. Use -1 to insert before the first residue.

              - `design_length_range: object { max, min }`

                Allowed sequence length range for designed regions

                - `max: number`

                  Maximum sequence length in residues. Must be >= min.

                - `min: number`

                  Minimum sequence length in residues

              - `type: "insertion"`

                - `"insertion"`

        - `StructureTemplateLigandChainSpec = object { chain_type }`

          Per-chain specification for a ligand chain in structure_template mode. The full ligand is always included.

          - `chain_type: "ligand"`

            - `"ligand"`

      - `modality: "peptide" or "antibody" or "nanobody" or "custom_protein"`

        - `"peptide"`

        - `"antibody"`

        - `"nanobody"`

        - `"custom_protein"`

      - `structure: object { url, url_expires_at }`

        - `url: string`

          URL to download the file

        - `url_expires_at: string`

          When the presigned URL expires

      - `type: "structure_template"`

        - `"structure_template"`

      - `rules: optional object { excluded_amino_acids, excluded_sequence_motifs, max_hydrophobic_fraction }`

        Constraints applied during sequence design

        - `excluded_amino_acids: optional array of string`

          Single-letter amino acid codes to exclude from design (e.g. ['C', 'P'] to exclude cysteine and proline)

        - `excluded_sequence_motifs: optional array of string`

          Sequence motifs to exclude from designed regions. Designs containing any of these motifs are filtered out before scoring. Use X as a single-residue wildcard (e.g. "NGS", "NXS").

        - `max_hydrophobic_fraction: optional number`

          Maximum allowed fraction of hydrophobic residues (I, L, V, M, F, W) in designed regions. Designs exceeding this threshold are filtered out before scoring. Leave empty to disable.

    - `NoTemplateBinderSpecResponse = object { entities, modality, type, 2 more }`

      Binder specification without a structural template. Define the binder from sequence components (fixed and designed segments) without providing a starting 3D structure.

      - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 3 more`

        Binder entities composing the design. At least one must be a designed_protein entity. Additional fixed entities (RNA, DNA, ligands) can be included as part of the complex.

        - `DesignedProteinEntityResponse = object { chain_ids, type, value, 2 more }`

          Protein binder entity with designed and/or fixed segments.

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "designed_protein"`

            - `"designed_protein"`

          - `value: string`

            Binder sequence specification. Fixed amino acids are written as literal single-letter codes. Designed regions are written as a length (fixed) or a length range (min..max). Example: "MKTAYI5..10VKSHFSRQ" means fixed MKTAYI, then 5-10 designed residues, then fixed VKSHFSRQ. "20" means 20 fully designed residues. "ACDE8GHI" means fixed ACDE, then 8 designed residues, then fixed GHI.

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Optional polymer modifications. Defaults to [] when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `FixedProteinEntityResponse = object { chain_ids, type, value, 2 more }`

          A fixed protein entity whose sequence is not redesigned.

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "protein"`

            - `"protein"`

          - `value: string`

            Amino acid sequence (one-letter codes)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Optional polymer modifications. Defaults to [] when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `FixedRnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "rna"`

            - `"rna"`

          - `value: string`

            RNA nucleotide sequence (A, C, G, U, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Optional polymer modifications. Defaults to [] when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `FixedDnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "dna"`

            - `"dna"`

          - `value: string`

            DNA nucleotide sequence (A, C, G, T, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Optional polymer modifications. Defaults to [] when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `FixedLigandSmilesEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "ligand_smiles"`

            - `"ligand_smiles"`

          - `value: string`

            SMILES string representing the ligand

        - `FixedLigandCcdEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "ligand_ccd"`

            - `"ligand_ccd"`

          - `value: string`

            CCD code from RCSB PDB (e.g. 'ATP', 'ADP')

      - `modality: "peptide" or "antibody" or "nanobody" or "custom_protein"`

        - `"peptide"`

        - `"antibody"`

        - `"nanobody"`

        - `"custom_protein"`

      - `type: "no_template"`

        - `"no_template"`

      - `bonds: optional array of object { atom1, atom2 }`

        Covalent bond constraints between atoms in the binder complex. If defining bonds where an atom is part of a designed protein chain, assume residue indices count designed regions as the minimum length. Example: designed protein "1..3C1..2", "C" is residue 1 (0-indexed) of the designed protein.

        - `atom1: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

        - `atom2: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

      - `rules: optional object { excluded_amino_acids, excluded_sequence_motifs, max_hydrophobic_fraction }`

        Constraints applied during sequence design

        - `excluded_amino_acids: optional array of string`

          Single-letter amino acid codes to exclude from design (e.g. ['C', 'P'] to exclude cysteine and proline)

        - `excluded_sequence_motifs: optional array of string`

          Sequence motifs to exclude from designed regions. Designs containing any of these motifs are filtered out before scoring. Use X as a single-residue wildcard (e.g. "NGS", "NXS").

        - `max_hydrophobic_fraction: optional number`

          Maximum allowed fraction of hydrophobic residues (I, L, V, M, F, W) in designed regions. Designs exceeding this threshold are filtered out before scoring. Leave empty to disable.

    - `BoltzCuratedBinderSpecResponse = object { binder, type, rules }`

      Boltz-managed curated binder specification. Choose a curated nanobody or antibody family and Boltz will select from maintained template lists during design. The curated lists are managed by Boltz and may be updated over time to improve quality and coverage.

      - `binder: "boltz_nanobody" or "boltz_antibody"`

        Boltz-managed curated binder family. Boltz maintains and may update the underlying template lists on behalf of customers.

        - `"boltz_nanobody"`

        - `"boltz_antibody"`

      - `type: "boltz_curated"`

        - `"boltz_curated"`

      - `rules: optional object { excluded_amino_acids, excluded_sequence_motifs, max_hydrophobic_fraction }`

        Constraints applied during sequence design

        - `excluded_amino_acids: optional array of string`

          Single-letter amino acid codes to exclude from design (e.g. ['C', 'P'] to exclude cysteine and proline)

        - `excluded_sequence_motifs: optional array of string`

          Sequence motifs to exclude from designed regions. Designs containing any of these motifs are filtered out before scoring. Use X as a single-residue wildcard (e.g. "NGS", "NXS").

        - `max_hydrophobic_fraction: optional number`

          Maximum allowed fraction of hydrophobic residues (I, L, V, M, F, W) in designed regions. Designs exceeding this threshold are filtered out before scoring. Leave empty to disable.

  - `num_proteins: number`

    Number of protein designs to generate. Must be between 10 and 1,000,000.

  - `target: object { chain_selection, structure, type }  or object { entities, type, bonds, 3 more }`

    Target specification (structure template or template-free)

    - `StructureTemplateTargetResponse = object { chain_selection, structure, type }`

      Target defined by an uploaded 3D structure (CIF or PDB file). Only chains included in chain_selection are used.

      - `chain_selection: map[object { chain_type, crop_residues, epitope_residues, flexible_residues }  or object { chain_type } ]`

        Chains selected from the uploaded structure, keyed by chain ID. Only chains listed here are included in the engine run — any chains omitted from this mapping are ignored. Each value defines which residues to keep, which are epitope residues, and which are flexible.

        - `StructureTemplateTargetPolymerChainSpec = object { chain_type, crop_residues, epitope_residues, flexible_residues }`

          Per-chain specification for a polymer (protein/RNA/DNA) chain in a structure template target.

          - `chain_type: "polymer"`

            - `"polymer"`

          - `crop_residues: array of number or "all"`

            0-indexed residue indices to retain from this chain, or 'all' to keep all residues. Residues not listed are excluded from the engine run.

            - `UnionMember0 = array of number`

              0-indexed residue indices to keep

            - `UnionMember1 = "all"`

              - `"all"`

          - `epitope_residues: optional array of number`

            0-indexed residue indices where binder contact is desired (the epitope). All indices must be present in crop_residues.

          - `flexible_residues: optional array of number`

            0-indexed residue indices allowed to move during design (e.g. flexible loop regions). All indices must be present in crop_residues.

        - `StructureTemplateTargetLigandChainSpec = object { chain_type }`

          Per-chain specification for a ligand chain in a structure template target. The full ligand is always included.

          - `chain_type: "ligand"`

            - `"ligand"`

      - `structure: object { url, url_expires_at }`

        - `url: string`

          URL to download the file

        - `url_expires_at: string`

          When the presigned URL expires

      - `type: "structure_template"`

        - `"structure_template"`

    - `NoTemplateTargetResponse = object { entities, type, bonds, 3 more }`

      Target defined by sequences only, without a 3D structure template

      - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 2 more`

        Entities (proteins, RNA, DNA, ligands) defining the target complex.

        - `ProteinEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "protein"`

            - `"protein"`

          - `value: string`

            Amino acid sequence (one-letter codes)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Post-translational modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `RnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "rna"`

            - `"rna"`

          - `value: string`

            RNA nucleotide sequence (A, C, G, U, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Chemical modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `DnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "dna"`

            - `"dna"`

          - `value: string`

            DNA nucleotide sequence (A, C, G, T, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Chemical modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `LigandCcdEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs for this ligand

          - `type: "ligand_ccd"`

            - `"ligand_ccd"`

          - `value: string`

            CCD code (e.g., ATP, ADP)

        - `LigandSmilesEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs for this ligand

          - `type: "ligand_smiles"`

            - `"ligand_smiles"`

          - `value: string`

            SMILES string representing the ligand

      - `type: "no_template"`

        - `"no_template"`

      - `bonds: optional array of object { atom1, atom2 }`

        Covalent bond constraints between atoms in the target complex. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

        - `atom1: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

        - `atom2: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

      - `constraints: optional array of object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }  or object { max_distance_angstrom, token1, token2, 2 more }`

        Structural constraints (pocket and contact). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

        - `PocketConstraintResponse = object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }`

          Constrains the binder to interact with specific pocket residues on the target.

          - `binder_chain_id: string`

            Chain ID of the binder molecule

          - `contact_residues: map[array of number]`

            Binding pocket residues keyed by chain ID. Each key is a chain ID (e.g. "A") and the value is an array of 0-indexed residue indices that define the pocket on that chain.

          - `max_distance_angstrom: number`

            Maximum allowed distance in Angstroms between binder and pocket residues. Typical range: 4-8 A.

          - `type: "pocket"`

            - `"pocket"`

          - `force: optional boolean`

            Whether to force the constraint

        - `ContactConstraintResponse = object { max_distance_angstrom, token1, token2, 2 more }`

          Contact constraint between two tokens. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `max_distance_angstrom: number`

            Maximum distance in Angstroms

          - `token1: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `PolymerContactTokenResponse = object { chain_id, residue_index, type }`

              - `chain_id: string`

                Chain ID

              - `residue_index: number`

                0-based residue index

              - `type: "polymer_contact"`

                - `"polymer_contact"`

            - `LigandContactTokenResponse = object { atom_name, chain_id, type }`

              Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

              - `atom_name: string`

                Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

              - `chain_id: string`

                Chain ID

              - `type: "ligand_contact"`

                - `"ligand_contact"`

          - `token2: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `PolymerContactTokenResponse = object { chain_id, residue_index, type }`

              - `chain_id: string`

                Chain ID

              - `residue_index: number`

                0-based residue index

              - `type: "polymer_contact"`

                - `"polymer_contact"`

            - `LigandContactTokenResponse = object { atom_name, chain_id, type }`

              Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

              - `atom_name: string`

                Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

              - `chain_id: string`

                Chain ID

              - `type: "ligand_contact"`

                - `"ligand_contact"`

          - `type: "contact"`

            - `"contact"`

          - `force: optional boolean`

            Whether to force the constraint

      - `epitope_ligand_chains: optional array of string`

        Chain IDs of ligand entities that are part of the binding epitope. Ligands are marked as epitope in full (no residue-level selection).

      - `epitope_residues: optional map[array of number]`

        Polymer chain residues where binder contact is desired (the epitope). Each key is a chain ID of a polymer entity, each value is an array of 0-indexed residue indices.

  - `idempotency_key: optional string`

    Client-provided key to prevent duplicate submissions on retries

  - `workspace_id: optional string`

    Target workspace ID (admin keys only; ignored for workspace keys)

- `livemode: boolean`

  Whether this resource was created with a live API key.

- `progress: object { num_proteins_generated, total_proteins_to_generate, latest_result_id }`

  - `num_proteins_generated: number`

    Number of protein binders generated so far

  - `total_proteins_to_generate: number`

    Total number of protein binders requested

  - `latest_result_id: optional string`

    ID of the most recently generated result

- `started_at: string`

- `status: "pending" or "running" or "succeeded" or 2 more`

  - `"pending"`

  - `"running"`

  - `"succeeded"`

  - `"failed"`

  - `"stopped"`

- `stopped_at: string`

- `workspace_id: string`

  Workspace ID

- `idempotency_key: optional string`

  Client-provided idempotency key

### Example

```http
curl https://api.boltz.bio/compute/v1/protein/design/$ID \
    -H "x-api-key: $BOLTZ_API_KEY"
```

## List Results

**get** `/compute/v1/protein/design/{id}/results`

Retrieve paginated results from a protein design run

### Path Parameters

- `id: string`

### Query Parameters

- `after_id: optional string`

  Return results after this ID

- `before_id: optional string`

  Return results before this ID

- `limit: optional number`

  Max results to return. Defaults to 100.

- `workspace_id: optional string`

  Workspace ID. Only used with admin API keys. Ignored (or validated) for workspace-scoped keys.

### Returns

- `data: array of object { id, artifacts, created_at, 3 more }`

  - `id: string`

    Unique result ID

  - `artifacts: object { archive, structure }`

    - `archive: object { url, url_expires_at }`

      - `url: string`

        URL to download the file

      - `url_expires_at: string`

        When the presigned URL expires

    - `structure: optional object { url, url_expires_at }`

      - `url: string`

        URL to download the file

      - `url_expires_at: string`

        When the presigned URL expires

  - `created_at: string`

  - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 2 more`

    Entities of the designed binder complex. Includes both designed entities and fixed entities from the input.

    - `ProteinEntity = object { chain_ids, type, value, 2 more }`

      - `chain_ids: array of string`

        Chain IDs for this entity

      - `type: "protein"`

        - `"protein"`

      - `value: string`

        Amino acid sequence (one-letter codes)

      - `cyclic: optional boolean`

        Whether the sequence is cyclic

      - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

        Post-translational modifications. Optional; defaults to an empty list when omitted.

        - `CcdModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "ccd"`

            - `"ccd"`

          - `value: string`

            CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

        - `SmilesModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "smiles"`

            - `"smiles"`

          - `value: string`

            SMILES string for the modification

    - `RnaEntity = object { chain_ids, type, value, 2 more }`

      - `chain_ids: array of string`

        Chain IDs for this entity

      - `type: "rna"`

        - `"rna"`

      - `value: string`

        RNA nucleotide sequence (A, C, G, U, N)

      - `cyclic: optional boolean`

        Whether the sequence is cyclic

      - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

        Chemical modifications. Optional; defaults to an empty list when omitted.

        - `CcdModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "ccd"`

            - `"ccd"`

          - `value: string`

            CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

        - `SmilesModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "smiles"`

            - `"smiles"`

          - `value: string`

            SMILES string for the modification

    - `DnaEntity = object { chain_ids, type, value, 2 more }`

      - `chain_ids: array of string`

        Chain IDs for this entity

      - `type: "dna"`

        - `"dna"`

      - `value: string`

        DNA nucleotide sequence (A, C, G, T, N)

      - `cyclic: optional boolean`

        Whether the sequence is cyclic

      - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

        Chemical modifications. Optional; defaults to an empty list when omitted.

        - `CcdModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "ccd"`

            - `"ccd"`

          - `value: string`

            CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

        - `SmilesModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "smiles"`

            - `"smiles"`

          - `value: string`

            SMILES string for the modification

    - `LigandCcdEntity = object { chain_ids, type, value }`

      - `chain_ids: array of string`

        Chain IDs for this ligand

      - `type: "ligand_ccd"`

        - `"ligand_ccd"`

      - `value: string`

        CCD code (e.g., ATP, ADP)

    - `LigandSmilesEntity = object { chain_ids, type, value }`

      - `chain_ids: array of string`

        Chain IDs for this ligand

      - `type: "ligand_smiles"`

        - `"ligand_smiles"`

      - `value: string`

        SMILES string representing the ligand

  - `metrics: object { binding_confidence, helix_fraction, iptm, 4 more }`

    Structural and binding quality metrics for a designed protein binder

    - `binding_confidence: number`

      Confidence that the designed binder binds the target (0-1). Primary metric for hit discovery.

    - `helix_fraction: number`

      Fraction of the designed sequence forming alpha helices (0-1).

    - `iptm: number`

      Interface predicted TM score (0-1). Confidence in the protein-protein interface.

    - `loop_fraction: number`

      Fraction of the designed sequence in coil/loop regions (0-1).

    - `min_interaction_pae: number`

      Minimum predicted aligned error at the interface (Angstroms). Lower values indicate higher confidence.

    - `sheet_fraction: number`

      Fraction of the designed sequence forming beta sheets (0-1).

    - `structure_confidence: number`

      Confidence in the predicted 3D structure (0-1).

  - `warnings: optional array of object { code, message }`

    Warnings about potential quality issues with this result.

    - `code: string`

      Machine-readable warning code (e.g. "low_confidence", "unusual_geometry")

    - `message: string`

      Human-readable description of the warning

- `first_id: string`

  ID of the first item. Use as before_id for the previous page.

- `has_more: boolean`

- `last_id: string`

  ID of the last item. Use as after_id for the next page.

### Example

```http
curl https://api.boltz.bio/compute/v1/protein/design/$ID/results \
    -H "x-api-key: $BOLTZ_API_KEY"
```

## Stop

**post** `/compute/v1/protein/design/{id}/stop`

Stop an in-progress protein design run early

### Path Parameters

- `id: string`

### Returns

- `id: string`

  Unique ProteinDesignRun identifier

- `completed_at: string`

- `created_at: string`

- `data_deleted_at: string`

  When the input, output, and result data was permanently deleted. Null if data has not been deleted.

- `engine: "boltz-protein-design"`

  Engine used for protein design

  - `"boltz-protein-design"`

- `engine_version: string`

  Engine version used for protein design

- `error: object { code, message, details }`

  - `code: string`

    Machine-readable error code

  - `message: string`

    Human-readable error message

  - `details: optional unknown`

    Additional field-level error details keyed by input path, when available.

- `input: object { binder_specification, num_proteins, target, 2 more }`

  Pipeline input (null if data deleted)

  - `binder_specification: object { chain_selection, modality, structure, 2 more }  or object { entities, modality, type, 2 more }  or object { binder, type, rules }`

    Binder specification for protein design. Use no_template for sequence-defined binders, structure_template for uploaded binder structures, or boltz_curated for Boltz-managed nanobody and antibody defaults.

    - `StructureTemplateBinderSpecResponse = object { chain_selection, modality, structure, 2 more }`

      Binder specification starting from an existing 3D structure. Upload a CIF/PDB file and select which chains to include, which residues to keep, and which regions to redesign. Only chains included in chain_selection are part of the engine run.

      - `chain_selection: map[object { chain_type, crop_residues, design_motifs }  or object { chain_type } ]`

        Chains selected from the uploaded binder structure, keyed by chain ID. Only chains listed here are included in the engine run — any chains omitted from this mapping are ignored. Each value defines which residues to keep (crop_residues). Omit design_motifs to include the chain as fixed scaffold context.

        - `StructureTemplatePolymerChainSpec = object { chain_type, crop_residues, design_motifs }`

          Per-chain crop and design specification for a polymer chain in structure_template mode.

          - `chain_type: "polymer"`

            - `"polymer"`

          - `crop_residues: array of number or "all"`

            0-indexed residue indices to retain from this chain, or 'all' to keep all residues. Residues not listed are removed before design.

            - `UnionMember0 = array of number`

            - `UnionMember1 = "all"`

              - `"all"`

          - `design_motifs: optional array of object { design_length_range, end_index, start_index, type }  or object { after_residue_index, design_length_range, type }`

            Optional motifs (replacement or insertion) defining which regions to redesign on this chain. Omit this field to include the chain as fixed scaffold context.

            - `ReplacementMotif = object { design_length_range, end_index, start_index, type }`

              Replace a contiguous region of the sequence with a designed segment. Residues from start_index to end_index (inclusive) are replaced with a new sequence of the specified length.

              - `design_length_range: object { max, min }`

                Allowed sequence length range for designed regions

                - `max: number`

                  Maximum sequence length in residues. Must be >= min.

                - `min: number`

                  Minimum sequence length in residues

              - `end_index: number`

                0-indexed end residue (inclusive)

              - `start_index: number`

                0-indexed start residue (inclusive)

              - `type: "replacement"`

                - `"replacement"`

            - `InsertionMotif = object { after_residue_index, design_length_range, type }`

              Insert a designed segment at a specific position in the sequence.

              - `after_residue_index: number`

                0-indexed position after which to insert. Use -1 to insert before the first residue.

              - `design_length_range: object { max, min }`

                Allowed sequence length range for designed regions

                - `max: number`

                  Maximum sequence length in residues. Must be >= min.

                - `min: number`

                  Minimum sequence length in residues

              - `type: "insertion"`

                - `"insertion"`

        - `StructureTemplateLigandChainSpec = object { chain_type }`

          Per-chain specification for a ligand chain in structure_template mode. The full ligand is always included.

          - `chain_type: "ligand"`

            - `"ligand"`

      - `modality: "peptide" or "antibody" or "nanobody" or "custom_protein"`

        - `"peptide"`

        - `"antibody"`

        - `"nanobody"`

        - `"custom_protein"`

      - `structure: object { url, url_expires_at }`

        - `url: string`

          URL to download the file

        - `url_expires_at: string`

          When the presigned URL expires

      - `type: "structure_template"`

        - `"structure_template"`

      - `rules: optional object { excluded_amino_acids, excluded_sequence_motifs, max_hydrophobic_fraction }`

        Constraints applied during sequence design

        - `excluded_amino_acids: optional array of string`

          Single-letter amino acid codes to exclude from design (e.g. ['C', 'P'] to exclude cysteine and proline)

        - `excluded_sequence_motifs: optional array of string`

          Sequence motifs to exclude from designed regions. Designs containing any of these motifs are filtered out before scoring. Use X as a single-residue wildcard (e.g. "NGS", "NXS").

        - `max_hydrophobic_fraction: optional number`

          Maximum allowed fraction of hydrophobic residues (I, L, V, M, F, W) in designed regions. Designs exceeding this threshold are filtered out before scoring. Leave empty to disable.

    - `NoTemplateBinderSpecResponse = object { entities, modality, type, 2 more }`

      Binder specification without a structural template. Define the binder from sequence components (fixed and designed segments) without providing a starting 3D structure.

      - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 3 more`

        Binder entities composing the design. At least one must be a designed_protein entity. Additional fixed entities (RNA, DNA, ligands) can be included as part of the complex.

        - `DesignedProteinEntityResponse = object { chain_ids, type, value, 2 more }`

          Protein binder entity with designed and/or fixed segments.

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "designed_protein"`

            - `"designed_protein"`

          - `value: string`

            Binder sequence specification. Fixed amino acids are written as literal single-letter codes. Designed regions are written as a length (fixed) or a length range (min..max). Example: "MKTAYI5..10VKSHFSRQ" means fixed MKTAYI, then 5-10 designed residues, then fixed VKSHFSRQ. "20" means 20 fully designed residues. "ACDE8GHI" means fixed ACDE, then 8 designed residues, then fixed GHI.

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Optional polymer modifications. Defaults to [] when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `FixedProteinEntityResponse = object { chain_ids, type, value, 2 more }`

          A fixed protein entity whose sequence is not redesigned.

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "protein"`

            - `"protein"`

          - `value: string`

            Amino acid sequence (one-letter codes)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Optional polymer modifications. Defaults to [] when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `FixedRnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "rna"`

            - `"rna"`

          - `value: string`

            RNA nucleotide sequence (A, C, G, U, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Optional polymer modifications. Defaults to [] when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `FixedDnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "dna"`

            - `"dna"`

          - `value: string`

            DNA nucleotide sequence (A, C, G, T, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Optional polymer modifications. Defaults to [] when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `FixedLigandSmilesEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "ligand_smiles"`

            - `"ligand_smiles"`

          - `value: string`

            SMILES string representing the ligand

        - `FixedLigandCcdEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs to assign to this entity

          - `type: "ligand_ccd"`

            - `"ligand_ccd"`

          - `value: string`

            CCD code from RCSB PDB (e.g. 'ATP', 'ADP')

      - `modality: "peptide" or "antibody" or "nanobody" or "custom_protein"`

        - `"peptide"`

        - `"antibody"`

        - `"nanobody"`

        - `"custom_protein"`

      - `type: "no_template"`

        - `"no_template"`

      - `bonds: optional array of object { atom1, atom2 }`

        Covalent bond constraints between atoms in the binder complex. If defining bonds where an atom is part of a designed protein chain, assume residue indices count designed regions as the minimum length. Example: designed protein "1..3C1..2", "C" is residue 1 (0-indexed) of the designed protein.

        - `atom1: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

        - `atom2: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

      - `rules: optional object { excluded_amino_acids, excluded_sequence_motifs, max_hydrophobic_fraction }`

        Constraints applied during sequence design

        - `excluded_amino_acids: optional array of string`

          Single-letter amino acid codes to exclude from design (e.g. ['C', 'P'] to exclude cysteine and proline)

        - `excluded_sequence_motifs: optional array of string`

          Sequence motifs to exclude from designed regions. Designs containing any of these motifs are filtered out before scoring. Use X as a single-residue wildcard (e.g. "NGS", "NXS").

        - `max_hydrophobic_fraction: optional number`

          Maximum allowed fraction of hydrophobic residues (I, L, V, M, F, W) in designed regions. Designs exceeding this threshold are filtered out before scoring. Leave empty to disable.

    - `BoltzCuratedBinderSpecResponse = object { binder, type, rules }`

      Boltz-managed curated binder specification. Choose a curated nanobody or antibody family and Boltz will select from maintained template lists during design. The curated lists are managed by Boltz and may be updated over time to improve quality and coverage.

      - `binder: "boltz_nanobody" or "boltz_antibody"`

        Boltz-managed curated binder family. Boltz maintains and may update the underlying template lists on behalf of customers.

        - `"boltz_nanobody"`

        - `"boltz_antibody"`

      - `type: "boltz_curated"`

        - `"boltz_curated"`

      - `rules: optional object { excluded_amino_acids, excluded_sequence_motifs, max_hydrophobic_fraction }`

        Constraints applied during sequence design

        - `excluded_amino_acids: optional array of string`

          Single-letter amino acid codes to exclude from design (e.g. ['C', 'P'] to exclude cysteine and proline)

        - `excluded_sequence_motifs: optional array of string`

          Sequence motifs to exclude from designed regions. Designs containing any of these motifs are filtered out before scoring. Use X as a single-residue wildcard (e.g. "NGS", "NXS").

        - `max_hydrophobic_fraction: optional number`

          Maximum allowed fraction of hydrophobic residues (I, L, V, M, F, W) in designed regions. Designs exceeding this threshold are filtered out before scoring. Leave empty to disable.

  - `num_proteins: number`

    Number of protein designs to generate. Must be between 10 and 1,000,000.

  - `target: object { chain_selection, structure, type }  or object { entities, type, bonds, 3 more }`

    Target specification (structure template or template-free)

    - `StructureTemplateTargetResponse = object { chain_selection, structure, type }`

      Target defined by an uploaded 3D structure (CIF or PDB file). Only chains included in chain_selection are used.

      - `chain_selection: map[object { chain_type, crop_residues, epitope_residues, flexible_residues }  or object { chain_type } ]`

        Chains selected from the uploaded structure, keyed by chain ID. Only chains listed here are included in the engine run — any chains omitted from this mapping are ignored. Each value defines which residues to keep, which are epitope residues, and which are flexible.

        - `StructureTemplateTargetPolymerChainSpec = object { chain_type, crop_residues, epitope_residues, flexible_residues }`

          Per-chain specification for a polymer (protein/RNA/DNA) chain in a structure template target.

          - `chain_type: "polymer"`

            - `"polymer"`

          - `crop_residues: array of number or "all"`

            0-indexed residue indices to retain from this chain, or 'all' to keep all residues. Residues not listed are excluded from the engine run.

            - `UnionMember0 = array of number`

              0-indexed residue indices to keep

            - `UnionMember1 = "all"`

              - `"all"`

          - `epitope_residues: optional array of number`

            0-indexed residue indices where binder contact is desired (the epitope). All indices must be present in crop_residues.

          - `flexible_residues: optional array of number`

            0-indexed residue indices allowed to move during design (e.g. flexible loop regions). All indices must be present in crop_residues.

        - `StructureTemplateTargetLigandChainSpec = object { chain_type }`

          Per-chain specification for a ligand chain in a structure template target. The full ligand is always included.

          - `chain_type: "ligand"`

            - `"ligand"`

      - `structure: object { url, url_expires_at }`

        - `url: string`

          URL to download the file

        - `url_expires_at: string`

          When the presigned URL expires

      - `type: "structure_template"`

        - `"structure_template"`

    - `NoTemplateTargetResponse = object { entities, type, bonds, 3 more }`

      Target defined by sequences only, without a 3D structure template

      - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 2 more`

        Entities (proteins, RNA, DNA, ligands) defining the target complex.

        - `ProteinEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "protein"`

            - `"protein"`

          - `value: string`

            Amino acid sequence (one-letter codes)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Post-translational modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `RnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "rna"`

            - `"rna"`

          - `value: string`

            RNA nucleotide sequence (A, C, G, U, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Chemical modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `DnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "dna"`

            - `"dna"`

          - `value: string`

            DNA nucleotide sequence (A, C, G, T, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Chemical modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `LigandCcdEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs for this ligand

          - `type: "ligand_ccd"`

            - `"ligand_ccd"`

          - `value: string`

            CCD code (e.g., ATP, ADP)

        - `LigandSmilesEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs for this ligand

          - `type: "ligand_smiles"`

            - `"ligand_smiles"`

          - `value: string`

            SMILES string representing the ligand

      - `type: "no_template"`

        - `"no_template"`

      - `bonds: optional array of object { atom1, atom2 }`

        Covalent bond constraints between atoms in the target complex. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

        - `atom1: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

        - `atom2: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

      - `constraints: optional array of object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }  or object { max_distance_angstrom, token1, token2, 2 more }`

        Structural constraints (pocket and contact). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

        - `PocketConstraintResponse = object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }`

          Constrains the binder to interact with specific pocket residues on the target.

          - `binder_chain_id: string`

            Chain ID of the binder molecule

          - `contact_residues: map[array of number]`

            Binding pocket residues keyed by chain ID. Each key is a chain ID (e.g. "A") and the value is an array of 0-indexed residue indices that define the pocket on that chain.

          - `max_distance_angstrom: number`

            Maximum allowed distance in Angstroms between binder and pocket residues. Typical range: 4-8 A.

          - `type: "pocket"`

            - `"pocket"`

          - `force: optional boolean`

            Whether to force the constraint

        - `ContactConstraintResponse = object { max_distance_angstrom, token1, token2, 2 more }`

          Contact constraint between two tokens. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `max_distance_angstrom: number`

            Maximum distance in Angstroms

          - `token1: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `PolymerContactTokenResponse = object { chain_id, residue_index, type }`

              - `chain_id: string`

                Chain ID

              - `residue_index: number`

                0-based residue index

              - `type: "polymer_contact"`

                - `"polymer_contact"`

            - `LigandContactTokenResponse = object { atom_name, chain_id, type }`

              Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

              - `atom_name: string`

                Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

              - `chain_id: string`

                Chain ID

              - `type: "ligand_contact"`

                - `"ligand_contact"`

          - `token2: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `PolymerContactTokenResponse = object { chain_id, residue_index, type }`

              - `chain_id: string`

                Chain ID

              - `residue_index: number`

                0-based residue index

              - `type: "polymer_contact"`

                - `"polymer_contact"`

            - `LigandContactTokenResponse = object { atom_name, chain_id, type }`

              Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

              - `atom_name: string`

                Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

              - `chain_id: string`

                Chain ID

              - `type: "ligand_contact"`

                - `"ligand_contact"`

          - `type: "contact"`

            - `"contact"`

          - `force: optional boolean`

            Whether to force the constraint

      - `epitope_ligand_chains: optional array of string`

        Chain IDs of ligand entities that are part of the binding epitope. Ligands are marked as epitope in full (no residue-level selection).

      - `epitope_residues: optional map[array of number]`

        Polymer chain residues where binder contact is desired (the epitope). Each key is a chain ID of a polymer entity, each value is an array of 0-indexed residue indices.

  - `idempotency_key: optional string`

    Client-provided key to prevent duplicate submissions on retries

  - `workspace_id: optional string`

    Target workspace ID (admin keys only; ignored for workspace keys)

- `livemode: boolean`

  Whether this resource was created with a live API key.

- `progress: object { num_proteins_generated, total_proteins_to_generate, latest_result_id }`

  - `num_proteins_generated: number`

    Number of protein binders generated so far

  - `total_proteins_to_generate: number`

    Total number of protein binders requested

  - `latest_result_id: optional string`

    ID of the most recently generated result

- `started_at: string`

- `status: "pending" or "running" or "succeeded" or 2 more`

  - `"pending"`

  - `"running"`

  - `"succeeded"`

  - `"failed"`

  - `"stopped"`

- `stopped_at: string`

- `workspace_id: string`

  Workspace ID

- `idempotency_key: optional string`

  Client-provided idempotency key

### Example

```http
curl https://api.boltz.bio/compute/v1/protein/design/$ID/stop \
    -X POST \
    -H "x-api-key: $BOLTZ_API_KEY"
```

## Delete Data

**post** `/compute/v1/protein/design/{id}/delete-data`

Permanently delete the input, output, and result data associated with this design run. The design run record itself is retained with a `data_deleted_at` timestamp. This action is irreversible.

### Path Parameters

- `id: string`

### Returns

- `id: string`

  ID of the resource whose data was deleted

- `data_deleted: true`

  - `true`

- `data_deleted_at: string`

  When the data was deleted

### Example

```http
curl https://api.boltz.bio/compute/v1/protein/design/$ID/delete-data \
    -X POST \
    -H "x-api-key: $BOLTZ_API_KEY"
```

## Estimate Cost

**post** `/compute/v1/protein/design/estimate-cost`

Estimate the cost of a protein design run without creating any resource or consuming GPU.

### Body Parameters

- `binder_specification: object { chain_selection, modality, structure, 2 more }  or object { entities, modality, type, 2 more }  or object { binder, type, rules }`

  Binder specification for protein design. Use no_template for sequence-defined binders, structure_template for uploaded binder structures, or boltz_curated for Boltz-managed nanobody and antibody defaults.

  - `StructureTemplateBinderSpec = object { chain_selection, modality, structure, 2 more }`

    Binder specification starting from an existing 3D structure. Upload a CIF/PDB file and select which chains to include, which residues to keep, and which regions to redesign. Only chains included in chain_selection are part of the engine run.

    - `chain_selection: map[object { chain_type, crop_residues, design_motifs }  or object { chain_type } ]`

      Chains selected from the uploaded binder structure, keyed by chain ID. Only chains listed here are included in the engine run — any chains omitted from this mapping are ignored. Each value defines which residues to keep (crop_residues). Omit design_motifs to include the chain as fixed scaffold context.

      - `StructureTemplatePolymerChainSpec = object { chain_type, crop_residues, design_motifs }`

        Per-chain crop and design specification for a polymer chain in structure_template mode.

        - `chain_type: "polymer"`

          - `"polymer"`

        - `crop_residues: array of number or "all"`

          0-indexed residue indices to retain from this chain, or 'all' to keep all residues. Residues not listed are removed before design.

          - `UnionMember0 = array of number`

          - `UnionMember1 = "all"`

            - `"all"`

        - `design_motifs: optional array of object { design_length_range, end_index, start_index, type }  or object { after_residue_index, design_length_range, type }`

          Optional motifs (replacement or insertion) defining which regions to redesign on this chain. Omit this field to include the chain as fixed scaffold context.

          - `ReplacementMotif = object { design_length_range, end_index, start_index, type }`

            Replace a contiguous region of the sequence with a designed segment. Residues from start_index to end_index (inclusive) are replaced with a new sequence of the specified length.

            - `design_length_range: object { max, min }`

              Allowed sequence length range for designed regions

              - `max: number`

                Maximum sequence length in residues. Must be >= min.

              - `min: number`

                Minimum sequence length in residues

            - `end_index: number`

              0-indexed end residue (inclusive)

            - `start_index: number`

              0-indexed start residue (inclusive)

            - `type: "replacement"`

              - `"replacement"`

          - `InsertionMotif = object { after_residue_index, design_length_range, type }`

            Insert a designed segment at a specific position in the sequence.

            - `after_residue_index: number`

              0-indexed position after which to insert. Use -1 to insert before the first residue.

            - `design_length_range: object { max, min }`

              Allowed sequence length range for designed regions

              - `max: number`

                Maximum sequence length in residues. Must be >= min.

              - `min: number`

                Minimum sequence length in residues

            - `type: "insertion"`

              - `"insertion"`

      - `StructureTemplateLigandChainSpec = object { chain_type }`

        Per-chain specification for a ligand chain in structure_template mode. The full ligand is always included.

        - `chain_type: "ligand"`

          - `"ligand"`

    - `modality: "peptide" or "antibody" or "nanobody" or "custom_protein"`

      - `"peptide"`

      - `"antibody"`

      - `"nanobody"`

      - `"custom_protein"`

    - `structure: object { type, url }  or object { data, media_type, type }`

      How to provide a CIF structure file. URLs are auto-detected; base64 uploads must use chemical/x-cif media type.

      - `URLSource = object { type, url }`

        - `type: "url"`

          - `"url"`

        - `url: string`

      - `CifBase64Source = object { data, media_type, type }`

        - `data: string`

          Base64-encoded CIF file contents

        - `media_type: "chemical/x-cif"`

          Must be chemical/x-cif for CIF files

          - `"chemical/x-cif"`

        - `type: "base64"`

          - `"base64"`

    - `type: "structure_template"`

      - `"structure_template"`

    - `rules: optional object { excluded_amino_acids, excluded_sequence_motifs, max_hydrophobic_fraction }`

      Constraints applied during sequence design

      - `excluded_amino_acids: optional array of string`

        Single-letter amino acid codes to exclude from design (e.g. ['C', 'P'] to exclude cysteine and proline)

      - `excluded_sequence_motifs: optional array of string`

        Sequence motifs to exclude from designed regions. Designs containing any of these motifs are filtered out before scoring. Use X as a single-residue wildcard (e.g. "NGS", "NXS").

      - `max_hydrophobic_fraction: optional number`

        Maximum allowed fraction of hydrophobic residues (I, L, V, M, F, W) in designed regions. Designs exceeding this threshold are filtered out before scoring. Leave empty to disable.

  - `NoTemplateBinderSpec = object { entities, modality, type, 2 more }`

    Binder specification without a structural template. Define the binder from sequence components (fixed and designed segments) without providing a starting 3D structure.

    - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 3 more`

      Binder entities composing the design. At least one must be a designed_protein entity. Additional fixed entities (RNA, DNA, ligands) can be included as part of the complex.

      - `DesignedProteinEntity = object { chain_ids, type, value, 2 more }`

        Protein binder entity with designed and/or fixed segments.

        - `chain_ids: array of string`

          Chain IDs to assign to this entity

        - `type: "designed_protein"`

          - `"designed_protein"`

        - `value: string`

          Binder sequence specification. Fixed amino acids are written as literal single-letter codes. Designed regions are written as a length (fixed) or a length range (min..max). Example: "MKTAYI5..10VKSHFSRQ" means fixed MKTAYI, then 5-10 designed residues, then fixed VKSHFSRQ. "20" means 20 fully designed residues. "ACDE8GHI" means fixed ACDE, then 8 designed residues, then fixed GHI.

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Optional polymer modifications. Defaults to [] when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `FixedProteinEntity = object { chain_ids, type, value, 2 more }`

        A fixed protein entity whose sequence is not redesigned.

        - `chain_ids: array of string`

          Chain IDs to assign to this entity

        - `type: "protein"`

          - `"protein"`

        - `value: string`

          Amino acid sequence (one-letter codes)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Optional polymer modifications. Defaults to [] when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `FixedRnaEntity = object { chain_ids, type, value, 2 more }`

        - `chain_ids: array of string`

          Chain IDs to assign to this entity

        - `type: "rna"`

          - `"rna"`

        - `value: string`

          RNA nucleotide sequence (A, C, G, U, N)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Optional polymer modifications. Defaults to [] when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `FixedDnaEntity = object { chain_ids, type, value, 2 more }`

        - `chain_ids: array of string`

          Chain IDs to assign to this entity

        - `type: "dna"`

          - `"dna"`

        - `value: string`

          DNA nucleotide sequence (A, C, G, T, N)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Optional polymer modifications. Defaults to [] when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `FixedLigandSmilesEntity = object { chain_ids, type, value }`

        - `chain_ids: array of string`

          Chain IDs to assign to this entity

        - `type: "ligand_smiles"`

          - `"ligand_smiles"`

        - `value: string`

          SMILES string representing the ligand

      - `FixedLigandCcdEntity = object { chain_ids, type, value }`

        - `chain_ids: array of string`

          Chain IDs to assign to this entity

        - `type: "ligand_ccd"`

          - `"ligand_ccd"`

        - `value: string`

          CCD code from RCSB PDB (e.g. 'ATP', 'ADP')

    - `modality: "peptide" or "antibody" or "nanobody" or "custom_protein"`

      - `"peptide"`

      - `"antibody"`

      - `"nanobody"`

      - `"custom_protein"`

    - `type: "no_template"`

      - `"no_template"`

    - `bonds: optional array of object { atom1, atom2 }`

      Covalent bond constraints between atoms in the binder complex. If defining bonds where an atom is part of a designed protein chain, assume residue indices count designed regions as the minimum length. Example: designed protein "1..3C1..2", "C" is residue 1 (0-indexed) of the designed protein.

      - `atom1: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

        Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

        - `LigandAtom = object { atom_name, chain_id, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

          - `chain_id: string`

            Chain ID containing the atom

          - `type: "ligand_atom"`

            - `"ligand_atom"`

        - `PolymerAtom = object { atom_name, chain_id, residue_index, type }`

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB)

          - `chain_id: string`

            Chain ID containing the atom

          - `residue_index: number`

            0-based residue index

          - `type: "polymer_atom"`

            - `"polymer_atom"`

      - `atom2: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

        Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

        - `LigandAtom = object { atom_name, chain_id, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

          - `chain_id: string`

            Chain ID containing the atom

          - `type: "ligand_atom"`

            - `"ligand_atom"`

        - `PolymerAtom = object { atom_name, chain_id, residue_index, type }`

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB)

          - `chain_id: string`

            Chain ID containing the atom

          - `residue_index: number`

            0-based residue index

          - `type: "polymer_atom"`

            - `"polymer_atom"`

    - `rules: optional object { excluded_amino_acids, excluded_sequence_motifs, max_hydrophobic_fraction }`

      Constraints applied during sequence design

      - `excluded_amino_acids: optional array of string`

        Single-letter amino acid codes to exclude from design (e.g. ['C', 'P'] to exclude cysteine and proline)

      - `excluded_sequence_motifs: optional array of string`

        Sequence motifs to exclude from designed regions. Designs containing any of these motifs are filtered out before scoring. Use X as a single-residue wildcard (e.g. "NGS", "NXS").

      - `max_hydrophobic_fraction: optional number`

        Maximum allowed fraction of hydrophobic residues (I, L, V, M, F, W) in designed regions. Designs exceeding this threshold are filtered out before scoring. Leave empty to disable.

  - `BoltzCuratedBinderSpec = object { binder, type, rules }`

    Boltz-managed curated binder specification. Choose a curated nanobody or antibody family and Boltz will select from maintained template lists during design. The curated lists are managed by Boltz and may be updated over time to improve quality and coverage.

    - `binder: "boltz_nanobody" or "boltz_antibody"`

      Boltz-managed curated binder family. Boltz maintains and may update the underlying template lists on behalf of customers.

      - `"boltz_nanobody"`

      - `"boltz_antibody"`

    - `type: "boltz_curated"`

      - `"boltz_curated"`

    - `rules: optional object { excluded_amino_acids, excluded_sequence_motifs, max_hydrophobic_fraction }`

      Constraints applied during sequence design

      - `excluded_amino_acids: optional array of string`

        Single-letter amino acid codes to exclude from design (e.g. ['C', 'P'] to exclude cysteine and proline)

      - `excluded_sequence_motifs: optional array of string`

        Sequence motifs to exclude from designed regions. Designs containing any of these motifs are filtered out before scoring. Use X as a single-residue wildcard (e.g. "NGS", "NXS").

      - `max_hydrophobic_fraction: optional number`

        Maximum allowed fraction of hydrophobic residues (I, L, V, M, F, W) in designed regions. Designs exceeding this threshold are filtered out before scoring. Leave empty to disable.

- `num_proteins: number`

  Number of protein designs to generate. Must be between 10 and 1,000,000.

- `target: object { chain_selection, structure, type }  or object { entities, type, bonds, 3 more }`

  Target specification (structure template or template-free)

  - `StructureTemplateTarget = object { chain_selection, structure, type }`

    Target defined by an uploaded 3D structure (CIF or PDB file). Only chains included in chain_selection are used.

    - `chain_selection: map[object { chain_type, crop_residues, epitope_residues, flexible_residues }  or object { chain_type } ]`

      Chains selected from the uploaded structure, keyed by chain ID. Only chains listed here are included in the engine run — any chains omitted from this mapping are ignored. Each value defines which residues to keep, which are epitope residues, and which are flexible.

      - `StructureTemplateTargetPolymerChainSpec = object { chain_type, crop_residues, epitope_residues, flexible_residues }`

        Per-chain specification for a polymer (protein/RNA/DNA) chain in a structure template target.

        - `chain_type: "polymer"`

          - `"polymer"`

        - `crop_residues: array of number or "all"`

          0-indexed residue indices to retain from this chain, or 'all' to keep all residues. Residues not listed are excluded from the engine run.

          - `UnionMember0 = array of number`

            0-indexed residue indices to keep

          - `UnionMember1 = "all"`

            - `"all"`

        - `epitope_residues: optional array of number`

          0-indexed residue indices where binder contact is desired (the epitope). All indices must be present in crop_residues.

        - `flexible_residues: optional array of number`

          0-indexed residue indices allowed to move during design (e.g. flexible loop regions). All indices must be present in crop_residues.

      - `StructureTemplateTargetLigandChainSpec = object { chain_type }`

        Per-chain specification for a ligand chain in a structure template target. The full ligand is always included.

        - `chain_type: "ligand"`

          - `"ligand"`

    - `structure: object { type, url }  or object { data, media_type, type }`

      How to provide a CIF structure file. URLs are auto-detected; base64 uploads must use chemical/x-cif media type.

      - `URLSource = object { type, url }`

        - `type: "url"`

          - `"url"`

        - `url: string`

      - `CifBase64Source = object { data, media_type, type }`

        - `data: string`

          Base64-encoded CIF file contents

        - `media_type: "chemical/x-cif"`

          Must be chemical/x-cif for CIF files

          - `"chemical/x-cif"`

        - `type: "base64"`

          - `"base64"`

    - `type: "structure_template"`

      - `"structure_template"`

  - `NoTemplateTarget = object { entities, type, bonds, 3 more }`

    Target defined by sequences only, without a 3D structure template

    - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 2 more`

      Entities (proteins, RNA, DNA, ligands) defining the target complex.

      - `ProteinEntity = object { chain_ids, type, value, 2 more }`

        - `chain_ids: array of string`

          Chain IDs for this entity

        - `type: "protein"`

          - `"protein"`

        - `value: string`

          Amino acid sequence (one-letter codes)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Post-translational modifications. Optional; defaults to an empty list when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `RnaEntity = object { chain_ids, type, value, 2 more }`

        - `chain_ids: array of string`

          Chain IDs for this entity

        - `type: "rna"`

          - `"rna"`

        - `value: string`

          RNA nucleotide sequence (A, C, G, U, N)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Chemical modifications. Optional; defaults to an empty list when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `DnaEntity = object { chain_ids, type, value, 2 more }`

        - `chain_ids: array of string`

          Chain IDs for this entity

        - `type: "dna"`

          - `"dna"`

        - `value: string`

          DNA nucleotide sequence (A, C, G, T, N)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Chemical modifications. Optional; defaults to an empty list when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `LigandCcdEntity = object { chain_ids, type, value }`

        - `chain_ids: array of string`

          Chain IDs for this ligand

        - `type: "ligand_ccd"`

          - `"ligand_ccd"`

        - `value: string`

          CCD code (e.g., ATP, ADP)

      - `LigandSmilesEntity = object { chain_ids, type, value }`

        - `chain_ids: array of string`

          Chain IDs for this ligand

        - `type: "ligand_smiles"`

          - `"ligand_smiles"`

        - `value: string`

          SMILES string representing the ligand

    - `type: "no_template"`

      - `"no_template"`

    - `bonds: optional array of object { atom1, atom2 }`

      Covalent bond constraints between atoms in the target complex. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

      - `atom1: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

        Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

        - `LigandAtom = object { atom_name, chain_id, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

          - `chain_id: string`

            Chain ID containing the atom

          - `type: "ligand_atom"`

            - `"ligand_atom"`

        - `PolymerAtom = object { atom_name, chain_id, residue_index, type }`

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB)

          - `chain_id: string`

            Chain ID containing the atom

          - `residue_index: number`

            0-based residue index

          - `type: "polymer_atom"`

            - `"polymer_atom"`

      - `atom2: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

        Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

        - `LigandAtom = object { atom_name, chain_id, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

          - `chain_id: string`

            Chain ID containing the atom

          - `type: "ligand_atom"`

            - `"ligand_atom"`

        - `PolymerAtom = object { atom_name, chain_id, residue_index, type }`

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB)

          - `chain_id: string`

            Chain ID containing the atom

          - `residue_index: number`

            0-based residue index

          - `type: "polymer_atom"`

            - `"polymer_atom"`

    - `constraints: optional array of object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }  or object { max_distance_angstrom, token1, token2, 2 more }`

      Structural constraints (pocket and contact). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

      - `PocketConstraint = object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }`

        Constrains the binder to interact with specific pocket residues on the target.

        - `binder_chain_id: string`

          Chain ID of the binder molecule

        - `contact_residues: map[array of number]`

          Binding pocket residues keyed by chain ID. Each key is a chain ID (e.g. "A") and the value is an array of 0-indexed residue indices that define the pocket on that chain.

        - `max_distance_angstrom: number`

          Maximum allowed distance in Angstroms between binder and pocket residues. Typical range: 4-8 A.

        - `type: "pocket"`

          - `"pocket"`

        - `force: optional boolean`

          Whether to force the constraint

      - `ContactConstraint = object { max_distance_angstrom, token1, token2, 2 more }`

        Contact constraint between two tokens. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

        - `max_distance_angstrom: number`

          Maximum distance in Angstroms

        - `token1: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

          Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `PolymerContactToken = object { chain_id, residue_index, type }`

            - `chain_id: string`

              Chain ID

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_contact"`

              - `"polymer_contact"`

          - `LigandContactToken = object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID

            - `type: "ligand_contact"`

              - `"ligand_contact"`

        - `token2: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

          Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `PolymerContactToken = object { chain_id, residue_index, type }`

            - `chain_id: string`

              Chain ID

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_contact"`

              - `"polymer_contact"`

          - `LigandContactToken = object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID

            - `type: "ligand_contact"`

              - `"ligand_contact"`

        - `type: "contact"`

          - `"contact"`

        - `force: optional boolean`

          Whether to force the constraint

    - `epitope_ligand_chains: optional array of string`

      Chain IDs of ligand entities that are part of the binding epitope. Ligands are marked as epitope in full (no residue-level selection).

    - `epitope_residues: optional map[array of number]`

      Polymer chain residues where binder contact is desired (the epitope). Each key is a chain ID of a polymer entity, each value is an array of 0-indexed residue indices.

- `idempotency_key: optional string`

  Client-provided key to prevent duplicate submissions on retries

- `workspace_id: optional string`

  Target workspace ID (admin keys only; ignored for workspace keys)

### Returns

- `breakdown: object { application, cost_per_unit_usd, num_units }`

  Cost breakdown for the billed application.

  - `application: "structure_and_binding" or "small_molecule_design" or "small_molecule_library_screen" or 3 more`

    - `"structure_and_binding"`

    - `"small_molecule_design"`

    - `"small_molecule_library_screen"`

    - `"protein_design"`

    - `"protein_library_screen"`

    - `"adme"`

  - `cost_per_unit_usd: string`

    Estimated cost per displayed unit as a decimal string, rounded up to 4 decimal places. This may include token-size multipliers or generation overhead; estimated_cost_usd is the authoritative total.

  - `num_units: number`

    Number of units shown for the estimate. For structure-and-binding, this is the requested number of samples. For protein and small-molecule design/screen endpoints, this is the requested number of proteins or molecules.

- `disclaimer: string`

- `estimated_cost_usd: string`

  Estimated total cost as a decimal string

### Example

```http
curl https://api.boltz.bio/compute/v1/protein/design/estimate-cost \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $BOLTZ_API_KEY" \
    -d '{
          "binder_specification": {
            "chain_selection": {
              "B": {
                "chain_type": "polymer",
                "crop_residues": [
                  0,
                  1,
                  2,
                  3,
                  4,
                  5,
                  6,
                  7,
                  8,
                  9
                ],
                "design_motifs": [
                  {
                    "design_length_range": {
                      "max": 8,
                      "min": 4
                    },
                    "end_index": 5,
                    "start_index": 0,
                    "type": "replacement"
                  }
                ]
              }
            },
            "modality": "peptide",
            "structure": {
              "type": "url",
              "url": "https://example.com"
            },
            "type": "structure_template"
          },
          "num_proteins": 10,
          "target": {
            "chain_selection": {
              "A": {
                "chain_type": "polymer",
                "crop_residues": [
                  0,
                  1,
                  2,
                  3,
                  4,
                  5,
                  6,
                  7,
                  8,
                  9,
                  10,
                  11,
                  12
                ],
                "epitope_residues": [
                  10,
                  11,
                  12
                ],
                "flexible_residues": [
                  5,
                  6,
                  7
                ]
              }
            },
            "structure": {
              "type": "url",
              "url": "https://example.com"
            },
            "type": "structure_template"
          }
        }'
```

# Library Screen

## Start

**post** `/compute/v1/protein/library-screen`

Screen a set of protein candidates against a target

### Body Parameters

- `proteins: array of object { entities, id }`

  List of protein entries to screen.

  - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 2 more`

    Entities that make up this protein complex

    - `ProteinEntity = object { chain_ids, type, value, 2 more }`

      - `chain_ids: array of string`

        Chain IDs for this entity

      - `type: "protein"`

        - `"protein"`

      - `value: string`

        Amino acid sequence (one-letter codes)

      - `cyclic: optional boolean`

        Whether the sequence is cyclic

      - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

        Post-translational modifications. Optional; defaults to an empty list when omitted.

        - `CcdModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "ccd"`

            - `"ccd"`

          - `value: string`

            CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

        - `SmilesModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "smiles"`

            - `"smiles"`

          - `value: string`

            SMILES string for the modification

    - `RnaEntity = object { chain_ids, type, value, 2 more }`

      - `chain_ids: array of string`

        Chain IDs for this entity

      - `type: "rna"`

        - `"rna"`

      - `value: string`

        RNA nucleotide sequence (A, C, G, U, N)

      - `cyclic: optional boolean`

        Whether the sequence is cyclic

      - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

        Chemical modifications. Optional; defaults to an empty list when omitted.

        - `CcdModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "ccd"`

            - `"ccd"`

          - `value: string`

            CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

        - `SmilesModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "smiles"`

            - `"smiles"`

          - `value: string`

            SMILES string for the modification

    - `DnaEntity = object { chain_ids, type, value, 2 more }`

      - `chain_ids: array of string`

        Chain IDs for this entity

      - `type: "dna"`

        - `"dna"`

      - `value: string`

        DNA nucleotide sequence (A, C, G, T, N)

      - `cyclic: optional boolean`

        Whether the sequence is cyclic

      - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

        Chemical modifications. Optional; defaults to an empty list when omitted.

        - `CcdModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "ccd"`

            - `"ccd"`

          - `value: string`

            CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

        - `SmilesModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "smiles"`

            - `"smiles"`

          - `value: string`

            SMILES string for the modification

    - `LigandCcdEntity = object { chain_ids, type, value }`

      - `chain_ids: array of string`

        Chain IDs for this ligand

      - `type: "ligand_ccd"`

        - `"ligand_ccd"`

      - `value: string`

        CCD code (e.g., ATP, ADP)

    - `LigandSmilesEntity = object { chain_ids, type, value }`

      - `chain_ids: array of string`

        Chain IDs for this ligand

      - `type: "ligand_smiles"`

        - `"ligand_smiles"`

      - `value: string`

        SMILES string representing the ligand

  - `id: optional string`

    Optional client-provided identifier for this entry

- `target: object { chain_selection, structure, type }  or object { entities, type, bonds, 3 more }`

  Target specification (structure template or template-free)

  - `StructureTemplateTarget = object { chain_selection, structure, type }`

    Target defined by an uploaded 3D structure (CIF or PDB file). Only chains included in chain_selection are used.

    - `chain_selection: map[object { chain_type, crop_residues, epitope_residues, flexible_residues }  or object { chain_type } ]`

      Chains selected from the uploaded structure, keyed by chain ID. Only chains listed here are included in the engine run — any chains omitted from this mapping are ignored. Each value defines which residues to keep, which are epitope residues, and which are flexible.

      - `StructureTemplateTargetPolymerChainSpec = object { chain_type, crop_residues, epitope_residues, flexible_residues }`

        Per-chain specification for a polymer (protein/RNA/DNA) chain in a structure template target.

        - `chain_type: "polymer"`

          - `"polymer"`

        - `crop_residues: array of number or "all"`

          0-indexed residue indices to retain from this chain, or 'all' to keep all residues. Residues not listed are excluded from the engine run.

          - `UnionMember0 = array of number`

            0-indexed residue indices to keep

          - `UnionMember1 = "all"`

            - `"all"`

        - `epitope_residues: optional array of number`

          0-indexed residue indices where binder contact is desired (the epitope). All indices must be present in crop_residues.

        - `flexible_residues: optional array of number`

          0-indexed residue indices allowed to move during design (e.g. flexible loop regions). All indices must be present in crop_residues.

      - `StructureTemplateTargetLigandChainSpec = object { chain_type }`

        Per-chain specification for a ligand chain in a structure template target. The full ligand is always included.

        - `chain_type: "ligand"`

          - `"ligand"`

    - `structure: object { type, url }  or object { data, media_type, type }`

      How to provide a CIF structure file. URLs are auto-detected; base64 uploads must use chemical/x-cif media type.

      - `URLSource = object { type, url }`

        - `type: "url"`

          - `"url"`

        - `url: string`

      - `CifBase64Source = object { data, media_type, type }`

        - `data: string`

          Base64-encoded CIF file contents

        - `media_type: "chemical/x-cif"`

          Must be chemical/x-cif for CIF files

          - `"chemical/x-cif"`

        - `type: "base64"`

          - `"base64"`

    - `type: "structure_template"`

      - `"structure_template"`

  - `NoTemplateTarget = object { entities, type, bonds, 3 more }`

    Target defined by sequences only, without a 3D structure template

    - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 2 more`

      Entities (proteins, RNA, DNA, ligands) defining the target complex.

      - `ProteinEntity = object { chain_ids, type, value, 2 more }`

        - `chain_ids: array of string`

          Chain IDs for this entity

        - `type: "protein"`

          - `"protein"`

        - `value: string`

          Amino acid sequence (one-letter codes)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Post-translational modifications. Optional; defaults to an empty list when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `RnaEntity = object { chain_ids, type, value, 2 more }`

        - `chain_ids: array of string`

          Chain IDs for this entity

        - `type: "rna"`

          - `"rna"`

        - `value: string`

          RNA nucleotide sequence (A, C, G, U, N)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Chemical modifications. Optional; defaults to an empty list when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `DnaEntity = object { chain_ids, type, value, 2 more }`

        - `chain_ids: array of string`

          Chain IDs for this entity

        - `type: "dna"`

          - `"dna"`

        - `value: string`

          DNA nucleotide sequence (A, C, G, T, N)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Chemical modifications. Optional; defaults to an empty list when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `LigandCcdEntity = object { chain_ids, type, value }`

        - `chain_ids: array of string`

          Chain IDs for this ligand

        - `type: "ligand_ccd"`

          - `"ligand_ccd"`

        - `value: string`

          CCD code (e.g., ATP, ADP)

      - `LigandSmilesEntity = object { chain_ids, type, value }`

        - `chain_ids: array of string`

          Chain IDs for this ligand

        - `type: "ligand_smiles"`

          - `"ligand_smiles"`

        - `value: string`

          SMILES string representing the ligand

    - `type: "no_template"`

      - `"no_template"`

    - `bonds: optional array of object { atom1, atom2 }`

      Covalent bond constraints between atoms in the target complex. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

      - `atom1: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

        Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

        - `LigandAtom = object { atom_name, chain_id, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

          - `chain_id: string`

            Chain ID containing the atom

          - `type: "ligand_atom"`

            - `"ligand_atom"`

        - `PolymerAtom = object { atom_name, chain_id, residue_index, type }`

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB)

          - `chain_id: string`

            Chain ID containing the atom

          - `residue_index: number`

            0-based residue index

          - `type: "polymer_atom"`

            - `"polymer_atom"`

      - `atom2: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

        Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

        - `LigandAtom = object { atom_name, chain_id, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

          - `chain_id: string`

            Chain ID containing the atom

          - `type: "ligand_atom"`

            - `"ligand_atom"`

        - `PolymerAtom = object { atom_name, chain_id, residue_index, type }`

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB)

          - `chain_id: string`

            Chain ID containing the atom

          - `residue_index: number`

            0-based residue index

          - `type: "polymer_atom"`

            - `"polymer_atom"`

    - `constraints: optional array of object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }  or object { max_distance_angstrom, token1, token2, 2 more }`

      Structural constraints (pocket and contact). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

      - `PocketConstraint = object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }`

        Constrains the binder to interact with specific pocket residues on the target.

        - `binder_chain_id: string`

          Chain ID of the binder molecule

        - `contact_residues: map[array of number]`

          Binding pocket residues keyed by chain ID. Each key is a chain ID (e.g. "A") and the value is an array of 0-indexed residue indices that define the pocket on that chain.

        - `max_distance_angstrom: number`

          Maximum allowed distance in Angstroms between binder and pocket residues. Typical range: 4-8 A.

        - `type: "pocket"`

          - `"pocket"`

        - `force: optional boolean`

          Whether to force the constraint

      - `ContactConstraint = object { max_distance_angstrom, token1, token2, 2 more }`

        Contact constraint between two tokens. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

        - `max_distance_angstrom: number`

          Maximum distance in Angstroms

        - `token1: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

          Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `PolymerContactToken = object { chain_id, residue_index, type }`

            - `chain_id: string`

              Chain ID

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_contact"`

              - `"polymer_contact"`

          - `LigandContactToken = object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID

            - `type: "ligand_contact"`

              - `"ligand_contact"`

        - `token2: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

          Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `PolymerContactToken = object { chain_id, residue_index, type }`

            - `chain_id: string`

              Chain ID

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_contact"`

              - `"polymer_contact"`

          - `LigandContactToken = object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID

            - `type: "ligand_contact"`

              - `"ligand_contact"`

        - `type: "contact"`

          - `"contact"`

        - `force: optional boolean`

          Whether to force the constraint

    - `epitope_ligand_chains: optional array of string`

      Chain IDs of ligand entities that are part of the binding epitope. Ligands are marked as epitope in full (no residue-level selection).

    - `epitope_residues: optional map[array of number]`

      Polymer chain residues where binder contact is desired (the epitope). Each key is a chain ID of a polymer entity, each value is an array of 0-indexed residue indices.

- `idempotency_key: optional string`

  Client-provided key to prevent duplicate submissions on retries

- `workspace_id: optional string`

  Target workspace ID (admin keys only; ignored for workspace keys)

### Returns

- `id: string`

  Unique ProteinLibraryScreen identifier

- `completed_at: string`

- `created_at: string`

- `data_deleted_at: string`

  When the input, output, and result data was permanently deleted. Null if data has not been deleted.

- `engine: "boltz-protein-screen"`

  Engine used for protein library screen

  - `"boltz-protein-screen"`

- `engine_version: string`

  Engine version used for protein library screen

- `error: object { code, message, details }`

  - `code: string`

    Machine-readable error code

  - `message: string`

    Human-readable error message

  - `details: optional unknown`

    Additional field-level error details keyed by input path, when available.

- `input: object { proteins, target }`

  Pipeline input (null if data deleted)

  - `proteins: object { url, url_expires_at }`

    - `url: string`

      URL to download the file

    - `url_expires_at: string`

      When the presigned URL expires

  - `target: object { chain_selection, structure, type }  or object { entities, type, bonds, 3 more }`

    Target specification (structure template or template-free)

    - `StructureTemplateTargetResponse = object { chain_selection, structure, type }`

      Target defined by an uploaded 3D structure (CIF or PDB file). Only chains included in chain_selection are used.

      - `chain_selection: map[object { chain_type, crop_residues, epitope_residues, flexible_residues }  or object { chain_type } ]`

        Chains selected from the uploaded structure, keyed by chain ID. Only chains listed here are included in the engine run — any chains omitted from this mapping are ignored. Each value defines which residues to keep, which are epitope residues, and which are flexible.

        - `StructureTemplateTargetPolymerChainSpec = object { chain_type, crop_residues, epitope_residues, flexible_residues }`

          Per-chain specification for a polymer (protein/RNA/DNA) chain in a structure template target.

          - `chain_type: "polymer"`

            - `"polymer"`

          - `crop_residues: array of number or "all"`

            0-indexed residue indices to retain from this chain, or 'all' to keep all residues. Residues not listed are excluded from the engine run.

            - `UnionMember0 = array of number`

              0-indexed residue indices to keep

            - `UnionMember1 = "all"`

              - `"all"`

          - `epitope_residues: optional array of number`

            0-indexed residue indices where binder contact is desired (the epitope). All indices must be present in crop_residues.

          - `flexible_residues: optional array of number`

            0-indexed residue indices allowed to move during design (e.g. flexible loop regions). All indices must be present in crop_residues.

        - `StructureTemplateTargetLigandChainSpec = object { chain_type }`

          Per-chain specification for a ligand chain in a structure template target. The full ligand is always included.

          - `chain_type: "ligand"`

            - `"ligand"`

      - `structure: object { url, url_expires_at }`

        - `url: string`

          URL to download the file

        - `url_expires_at: string`

          When the presigned URL expires

      - `type: "structure_template"`

        - `"structure_template"`

    - `NoTemplateTargetResponse = object { entities, type, bonds, 3 more }`

      Target defined by sequences only, without a 3D structure template

      - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 2 more`

        Entities (proteins, RNA, DNA, ligands) defining the target complex.

        - `ProteinEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "protein"`

            - `"protein"`

          - `value: string`

            Amino acid sequence (one-letter codes)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Post-translational modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `RnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "rna"`

            - `"rna"`

          - `value: string`

            RNA nucleotide sequence (A, C, G, U, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Chemical modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `DnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "dna"`

            - `"dna"`

          - `value: string`

            DNA nucleotide sequence (A, C, G, T, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Chemical modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `LigandCcdEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs for this ligand

          - `type: "ligand_ccd"`

            - `"ligand_ccd"`

          - `value: string`

            CCD code (e.g., ATP, ADP)

        - `LigandSmilesEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs for this ligand

          - `type: "ligand_smiles"`

            - `"ligand_smiles"`

          - `value: string`

            SMILES string representing the ligand

      - `type: "no_template"`

        - `"no_template"`

      - `bonds: optional array of object { atom1, atom2 }`

        Covalent bond constraints between atoms in the target complex. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

        - `atom1: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

        - `atom2: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

      - `constraints: optional array of object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }  or object { max_distance_angstrom, token1, token2, 2 more }`

        Structural constraints (pocket and contact). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

        - `PocketConstraintResponse = object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }`

          Constrains the binder to interact with specific pocket residues on the target.

          - `binder_chain_id: string`

            Chain ID of the binder molecule

          - `contact_residues: map[array of number]`

            Binding pocket residues keyed by chain ID. Each key is a chain ID (e.g. "A") and the value is an array of 0-indexed residue indices that define the pocket on that chain.

          - `max_distance_angstrom: number`

            Maximum allowed distance in Angstroms between binder and pocket residues. Typical range: 4-8 A.

          - `type: "pocket"`

            - `"pocket"`

          - `force: optional boolean`

            Whether to force the constraint

        - `ContactConstraintResponse = object { max_distance_angstrom, token1, token2, 2 more }`

          Contact constraint between two tokens. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `max_distance_angstrom: number`

            Maximum distance in Angstroms

          - `token1: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `PolymerContactTokenResponse = object { chain_id, residue_index, type }`

              - `chain_id: string`

                Chain ID

              - `residue_index: number`

                0-based residue index

              - `type: "polymer_contact"`

                - `"polymer_contact"`

            - `LigandContactTokenResponse = object { atom_name, chain_id, type }`

              Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

              - `atom_name: string`

                Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

              - `chain_id: string`

                Chain ID

              - `type: "ligand_contact"`

                - `"ligand_contact"`

          - `token2: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `PolymerContactTokenResponse = object { chain_id, residue_index, type }`

              - `chain_id: string`

                Chain ID

              - `residue_index: number`

                0-based residue index

              - `type: "polymer_contact"`

                - `"polymer_contact"`

            - `LigandContactTokenResponse = object { atom_name, chain_id, type }`

              Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

              - `atom_name: string`

                Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

              - `chain_id: string`

                Chain ID

              - `type: "ligand_contact"`

                - `"ligand_contact"`

          - `type: "contact"`

            - `"contact"`

          - `force: optional boolean`

            Whether to force the constraint

      - `epitope_ligand_chains: optional array of string`

        Chain IDs of ligand entities that are part of the binding epitope. Ligands are marked as epitope in full (no residue-level selection).

      - `epitope_residues: optional map[array of number]`

        Polymer chain residues where binder contact is desired (the epitope). Each key is a chain ID of a polymer entity, each value is an array of 0-indexed residue indices.

- `livemode: boolean`

  Whether this resource was created with a live API key.

- `progress: object { num_proteins_failed, num_proteins_screened, total_proteins_to_screen, latest_result_id }`

  - `num_proteins_failed: number`

    Number of accepted proteins that reached terminal failure during screening.

  - `num_proteins_screened: number`

    Number of accepted proteins that produced usable screening results.

  - `total_proteins_to_screen: number`

    Total number of proteins accepted into the screening run.

  - `latest_result_id: optional string`

    ID of the latest result

- `started_at: string`

- `status: "pending" or "running" or "succeeded" or 2 more`

  - `"pending"`

  - `"running"`

  - `"succeeded"`

  - `"failed"`

  - `"stopped"`

- `stopped_at: string`

- `workspace_id: string`

  Workspace ID

- `idempotency_key: optional string`

  Client-provided idempotency key

### Example

```http
curl https://api.boltz.bio/compute/v1/protein/library-screen \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $BOLTZ_API_KEY" \
    -d '{
          "proteins": [
            {
              "entities": [
                {
                  "chain_ids": [
                    "string"
                  ],
                  "type": "protein",
                  "value": "value"
                }
              ]
            }
          ],
          "target": {
            "chain_selection": {
              "A": {
                "chain_type": "polymer",
                "crop_residues": [
                  0,
                  1,
                  2,
                  3,
                  4,
                  5,
                  6,
                  7,
                  8,
                  9,
                  10,
                  11,
                  12
                ],
                "epitope_residues": [
                  10,
                  11,
                  12
                ],
                "flexible_residues": [
                  5,
                  6,
                  7
                ]
              }
            },
            "structure": {
              "type": "url",
              "url": "https://example.com"
            },
            "type": "structure_template"
          }
        }'
```

## List

**get** `/compute/v1/protein/library-screen`

List protein library screens, optionally filtered by workspace

### Query Parameters

- `after_id: optional string`

  Return results after this ID

- `before_id: optional string`

  Return results before this ID

- `limit: optional number`

  Max items to return. Defaults to 100.

- `workspace_id: optional string`

  Filter by workspace ID. Only used with admin API keys. If not provided, defaults to the workspace associated with the API key, or the default workspace for admin keys.

### Returns

- `data: array of object { id, completed_at, created_at, 11 more }`

  - `id: string`

    Unique ProteinLibraryScreenSummary identifier

  - `completed_at: string`

  - `created_at: string`

  - `data_deleted_at: string`

    When the input, output, and result data was permanently deleted. Null if data has not been deleted.

  - `engine: "boltz-protein-screen"`

    Engine used for protein library screen

    - `"boltz-protein-screen"`

  - `engine_version: string`

    Engine version used for protein library screen

  - `error: object { code, message, details }`

    - `code: string`

      Machine-readable error code

    - `message: string`

      Human-readable error message

    - `details: optional unknown`

      Additional field-level error details keyed by input path, when available.

  - `livemode: boolean`

    Whether this resource was created with a live API key.

  - `progress: object { num_proteins_failed, num_proteins_screened, total_proteins_to_screen, latest_result_id }`

    - `num_proteins_failed: number`

      Number of accepted proteins that reached terminal failure during screening.

    - `num_proteins_screened: number`

      Number of accepted proteins that produced usable screening results.

    - `total_proteins_to_screen: number`

      Total number of proteins accepted into the screening run.

    - `latest_result_id: optional string`

      ID of the latest result

  - `started_at: string`

  - `status: "pending" or "running" or "succeeded" or 2 more`

    - `"pending"`

    - `"running"`

    - `"succeeded"`

    - `"failed"`

    - `"stopped"`

  - `stopped_at: string`

  - `workspace_id: string`

    Workspace ID

  - `idempotency_key: optional string`

    Client-provided idempotency key

- `first_id: string`

  ID of the first item. Use as before_id for the previous page.

- `has_more: boolean`

- `last_id: string`

  ID of the last item. Use as after_id for the next page.

### Example

```http
curl https://api.boltz.bio/compute/v1/protein/library-screen \
    -H "x-api-key: $BOLTZ_API_KEY"
```

## Retrieve

**get** `/compute/v1/protein/library-screen/{id}`

Retrieve a library screen by ID, including progress and status

### Path Parameters

- `id: string`

### Query Parameters

- `workspace_id: optional string`

  Workspace ID. Only used with admin API keys. Ignored (or validated) for workspace-scoped keys.

### Returns

- `id: string`

  Unique ProteinLibraryScreen identifier

- `completed_at: string`

- `created_at: string`

- `data_deleted_at: string`

  When the input, output, and result data was permanently deleted. Null if data has not been deleted.

- `engine: "boltz-protein-screen"`

  Engine used for protein library screen

  - `"boltz-protein-screen"`

- `engine_version: string`

  Engine version used for protein library screen

- `error: object { code, message, details }`

  - `code: string`

    Machine-readable error code

  - `message: string`

    Human-readable error message

  - `details: optional unknown`

    Additional field-level error details keyed by input path, when available.

- `input: object { proteins, target }`

  Pipeline input (null if data deleted)

  - `proteins: object { url, url_expires_at }`

    - `url: string`

      URL to download the file

    - `url_expires_at: string`

      When the presigned URL expires

  - `target: object { chain_selection, structure, type }  or object { entities, type, bonds, 3 more }`

    Target specification (structure template or template-free)

    - `StructureTemplateTargetResponse = object { chain_selection, structure, type }`

      Target defined by an uploaded 3D structure (CIF or PDB file). Only chains included in chain_selection are used.

      - `chain_selection: map[object { chain_type, crop_residues, epitope_residues, flexible_residues }  or object { chain_type } ]`

        Chains selected from the uploaded structure, keyed by chain ID. Only chains listed here are included in the engine run — any chains omitted from this mapping are ignored. Each value defines which residues to keep, which are epitope residues, and which are flexible.

        - `StructureTemplateTargetPolymerChainSpec = object { chain_type, crop_residues, epitope_residues, flexible_residues }`

          Per-chain specification for a polymer (protein/RNA/DNA) chain in a structure template target.

          - `chain_type: "polymer"`

            - `"polymer"`

          - `crop_residues: array of number or "all"`

            0-indexed residue indices to retain from this chain, or 'all' to keep all residues. Residues not listed are excluded from the engine run.

            - `UnionMember0 = array of number`

              0-indexed residue indices to keep

            - `UnionMember1 = "all"`

              - `"all"`

          - `epitope_residues: optional array of number`

            0-indexed residue indices where binder contact is desired (the epitope). All indices must be present in crop_residues.

          - `flexible_residues: optional array of number`

            0-indexed residue indices allowed to move during design (e.g. flexible loop regions). All indices must be present in crop_residues.

        - `StructureTemplateTargetLigandChainSpec = object { chain_type }`

          Per-chain specification for a ligand chain in a structure template target. The full ligand is always included.

          - `chain_type: "ligand"`

            - `"ligand"`

      - `structure: object { url, url_expires_at }`

        - `url: string`

          URL to download the file

        - `url_expires_at: string`

          When the presigned URL expires

      - `type: "structure_template"`

        - `"structure_template"`

    - `NoTemplateTargetResponse = object { entities, type, bonds, 3 more }`

      Target defined by sequences only, without a 3D structure template

      - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 2 more`

        Entities (proteins, RNA, DNA, ligands) defining the target complex.

        - `ProteinEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "protein"`

            - `"protein"`

          - `value: string`

            Amino acid sequence (one-letter codes)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Post-translational modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `RnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "rna"`

            - `"rna"`

          - `value: string`

            RNA nucleotide sequence (A, C, G, U, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Chemical modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `DnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "dna"`

            - `"dna"`

          - `value: string`

            DNA nucleotide sequence (A, C, G, T, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Chemical modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `LigandCcdEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs for this ligand

          - `type: "ligand_ccd"`

            - `"ligand_ccd"`

          - `value: string`

            CCD code (e.g., ATP, ADP)

        - `LigandSmilesEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs for this ligand

          - `type: "ligand_smiles"`

            - `"ligand_smiles"`

          - `value: string`

            SMILES string representing the ligand

      - `type: "no_template"`

        - `"no_template"`

      - `bonds: optional array of object { atom1, atom2 }`

        Covalent bond constraints between atoms in the target complex. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

        - `atom1: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

        - `atom2: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

      - `constraints: optional array of object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }  or object { max_distance_angstrom, token1, token2, 2 more }`

        Structural constraints (pocket and contact). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

        - `PocketConstraintResponse = object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }`

          Constrains the binder to interact with specific pocket residues on the target.

          - `binder_chain_id: string`

            Chain ID of the binder molecule

          - `contact_residues: map[array of number]`

            Binding pocket residues keyed by chain ID. Each key is a chain ID (e.g. "A") and the value is an array of 0-indexed residue indices that define the pocket on that chain.

          - `max_distance_angstrom: number`

            Maximum allowed distance in Angstroms between binder and pocket residues. Typical range: 4-8 A.

          - `type: "pocket"`

            - `"pocket"`

          - `force: optional boolean`

            Whether to force the constraint

        - `ContactConstraintResponse = object { max_distance_angstrom, token1, token2, 2 more }`

          Contact constraint between two tokens. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `max_distance_angstrom: number`

            Maximum distance in Angstroms

          - `token1: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `PolymerContactTokenResponse = object { chain_id, residue_index, type }`

              - `chain_id: string`

                Chain ID

              - `residue_index: number`

                0-based residue index

              - `type: "polymer_contact"`

                - `"polymer_contact"`

            - `LigandContactTokenResponse = object { atom_name, chain_id, type }`

              Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

              - `atom_name: string`

                Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

              - `chain_id: string`

                Chain ID

              - `type: "ligand_contact"`

                - `"ligand_contact"`

          - `token2: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `PolymerContactTokenResponse = object { chain_id, residue_index, type }`

              - `chain_id: string`

                Chain ID

              - `residue_index: number`

                0-based residue index

              - `type: "polymer_contact"`

                - `"polymer_contact"`

            - `LigandContactTokenResponse = object { atom_name, chain_id, type }`

              Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

              - `atom_name: string`

                Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

              - `chain_id: string`

                Chain ID

              - `type: "ligand_contact"`

                - `"ligand_contact"`

          - `type: "contact"`

            - `"contact"`

          - `force: optional boolean`

            Whether to force the constraint

      - `epitope_ligand_chains: optional array of string`

        Chain IDs of ligand entities that are part of the binding epitope. Ligands are marked as epitope in full (no residue-level selection).

      - `epitope_residues: optional map[array of number]`

        Polymer chain residues where binder contact is desired (the epitope). Each key is a chain ID of a polymer entity, each value is an array of 0-indexed residue indices.

- `livemode: boolean`

  Whether this resource was created with a live API key.

- `progress: object { num_proteins_failed, num_proteins_screened, total_proteins_to_screen, latest_result_id }`

  - `num_proteins_failed: number`

    Number of accepted proteins that reached terminal failure during screening.

  - `num_proteins_screened: number`

    Number of accepted proteins that produced usable screening results.

  - `total_proteins_to_screen: number`

    Total number of proteins accepted into the screening run.

  - `latest_result_id: optional string`

    ID of the latest result

- `started_at: string`

- `status: "pending" or "running" or "succeeded" or 2 more`

  - `"pending"`

  - `"running"`

  - `"succeeded"`

  - `"failed"`

  - `"stopped"`

- `stopped_at: string`

- `workspace_id: string`

  Workspace ID

- `idempotency_key: optional string`

  Client-provided idempotency key

### Example

```http
curl https://api.boltz.bio/compute/v1/protein/library-screen/$ID \
    -H "x-api-key: $BOLTZ_API_KEY"
```

## List Results

**get** `/compute/v1/protein/library-screen/{id}/results`

Retrieve paginated results from a protein library screen

### Path Parameters

- `id: string`

### Query Parameters

- `after_id: optional string`

  Return results after this ID

- `before_id: optional string`

  Return results before this ID

- `limit: optional number`

  Max results to return. Defaults to 100.

- `workspace_id: optional string`

  Workspace ID. Only used with admin API keys. Ignored (or validated) for workspace-scoped keys.

### Returns

- `data: array of object { id, artifacts, created_at, 4 more }`

  - `id: string`

    Unique result ID

  - `artifacts: object { archive, structure }`

    - `archive: object { url, url_expires_at }`

      - `url: string`

        URL to download the file

      - `url_expires_at: string`

        When the presigned URL expires

    - `structure: object { url, url_expires_at }`

      - `url: string`

        URL to download the file

      - `url_expires_at: string`

        When the presigned URL expires

  - `created_at: string`

  - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 2 more`

    Entities of the screened complex. Includes both screened and fixed entities from the input.

    - `ProteinEntity = object { chain_ids, type, value, 2 more }`

      - `chain_ids: array of string`

        Chain IDs for this entity

      - `type: "protein"`

        - `"protein"`

      - `value: string`

        Amino acid sequence (one-letter codes)

      - `cyclic: optional boolean`

        Whether the sequence is cyclic

      - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

        Post-translational modifications. Optional; defaults to an empty list when omitted.

        - `CcdModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "ccd"`

            - `"ccd"`

          - `value: string`

            CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

        - `SmilesModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "smiles"`

            - `"smiles"`

          - `value: string`

            SMILES string for the modification

    - `RnaEntity = object { chain_ids, type, value, 2 more }`

      - `chain_ids: array of string`

        Chain IDs for this entity

      - `type: "rna"`

        - `"rna"`

      - `value: string`

        RNA nucleotide sequence (A, C, G, U, N)

      - `cyclic: optional boolean`

        Whether the sequence is cyclic

      - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

        Chemical modifications. Optional; defaults to an empty list when omitted.

        - `CcdModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "ccd"`

            - `"ccd"`

          - `value: string`

            CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

        - `SmilesModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "smiles"`

            - `"smiles"`

          - `value: string`

            SMILES string for the modification

    - `DnaEntity = object { chain_ids, type, value, 2 more }`

      - `chain_ids: array of string`

        Chain IDs for this entity

      - `type: "dna"`

        - `"dna"`

      - `value: string`

        DNA nucleotide sequence (A, C, G, T, N)

      - `cyclic: optional boolean`

        Whether the sequence is cyclic

      - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

        Chemical modifications. Optional; defaults to an empty list when omitted.

        - `CcdModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "ccd"`

            - `"ccd"`

          - `value: string`

            CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

        - `SmilesModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "smiles"`

            - `"smiles"`

          - `value: string`

            SMILES string for the modification

    - `LigandCcdEntity = object { chain_ids, type, value }`

      - `chain_ids: array of string`

        Chain IDs for this ligand

      - `type: "ligand_ccd"`

        - `"ligand_ccd"`

      - `value: string`

        CCD code (e.g., ATP, ADP)

    - `LigandSmilesEntity = object { chain_ids, type, value }`

      - `chain_ids: array of string`

        Chain IDs for this ligand

      - `type: "ligand_smiles"`

        - `"ligand_smiles"`

      - `value: string`

        SMILES string representing the ligand

  - `metrics: object { binding_confidence, helix_fraction, iptm, 4 more }`

    Structural and binding quality metrics for a screened protein

    - `binding_confidence: number`

      Confidence that the protein binds the target (0-1). Primary metric for hit discovery.

    - `helix_fraction: number`

      Fraction of the sequence forming alpha helices (0-1).

    - `iptm: number`

      Interface predicted TM score (0-1). Confidence in the protein-protein interface.

    - `loop_fraction: number`

      Fraction of the sequence in coil/loop regions (0-1).

    - `min_interaction_pae: number`

      Minimum predicted aligned error at the interface (Angstroms). Lower values indicate higher confidence.

    - `sheet_fraction: number`

      Fraction of the sequence forming beta sheets (0-1).

    - `structure_confidence: number`

      Confidence in the predicted 3D structure (0-1).

  - `external_id: optional string`

    Client-provided identifier for this protein, if provided

  - `warnings: optional array of object { code, message }`

    Warnings about potential quality issues with this result.

    - `code: string`

      Machine-readable warning code (e.g. "low_confidence", "unusual_geometry")

    - `message: string`

      Human-readable description of the warning

- `first_id: string`

  ID of the first item. Use as before_id for the previous page.

- `has_more: boolean`

- `last_id: string`

  ID of the last item. Use as after_id for the next page.

### Example

```http
curl https://api.boltz.bio/compute/v1/protein/library-screen/$ID/results \
    -H "x-api-key: $BOLTZ_API_KEY"
```

## Stop

**post** `/compute/v1/protein/library-screen/{id}/stop`

Stop an in-progress protein library screen early

### Path Parameters

- `id: string`

### Returns

- `id: string`

  Unique ProteinLibraryScreen identifier

- `completed_at: string`

- `created_at: string`

- `data_deleted_at: string`

  When the input, output, and result data was permanently deleted. Null if data has not been deleted.

- `engine: "boltz-protein-screen"`

  Engine used for protein library screen

  - `"boltz-protein-screen"`

- `engine_version: string`

  Engine version used for protein library screen

- `error: object { code, message, details }`

  - `code: string`

    Machine-readable error code

  - `message: string`

    Human-readable error message

  - `details: optional unknown`

    Additional field-level error details keyed by input path, when available.

- `input: object { proteins, target }`

  Pipeline input (null if data deleted)

  - `proteins: object { url, url_expires_at }`

    - `url: string`

      URL to download the file

    - `url_expires_at: string`

      When the presigned URL expires

  - `target: object { chain_selection, structure, type }  or object { entities, type, bonds, 3 more }`

    Target specification (structure template or template-free)

    - `StructureTemplateTargetResponse = object { chain_selection, structure, type }`

      Target defined by an uploaded 3D structure (CIF or PDB file). Only chains included in chain_selection are used.

      - `chain_selection: map[object { chain_type, crop_residues, epitope_residues, flexible_residues }  or object { chain_type } ]`

        Chains selected from the uploaded structure, keyed by chain ID. Only chains listed here are included in the engine run — any chains omitted from this mapping are ignored. Each value defines which residues to keep, which are epitope residues, and which are flexible.

        - `StructureTemplateTargetPolymerChainSpec = object { chain_type, crop_residues, epitope_residues, flexible_residues }`

          Per-chain specification for a polymer (protein/RNA/DNA) chain in a structure template target.

          - `chain_type: "polymer"`

            - `"polymer"`

          - `crop_residues: array of number or "all"`

            0-indexed residue indices to retain from this chain, or 'all' to keep all residues. Residues not listed are excluded from the engine run.

            - `UnionMember0 = array of number`

              0-indexed residue indices to keep

            - `UnionMember1 = "all"`

              - `"all"`

          - `epitope_residues: optional array of number`

            0-indexed residue indices where binder contact is desired (the epitope). All indices must be present in crop_residues.

          - `flexible_residues: optional array of number`

            0-indexed residue indices allowed to move during design (e.g. flexible loop regions). All indices must be present in crop_residues.

        - `StructureTemplateTargetLigandChainSpec = object { chain_type }`

          Per-chain specification for a ligand chain in a structure template target. The full ligand is always included.

          - `chain_type: "ligand"`

            - `"ligand"`

      - `structure: object { url, url_expires_at }`

        - `url: string`

          URL to download the file

        - `url_expires_at: string`

          When the presigned URL expires

      - `type: "structure_template"`

        - `"structure_template"`

    - `NoTemplateTargetResponse = object { entities, type, bonds, 3 more }`

      Target defined by sequences only, without a 3D structure template

      - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 2 more`

        Entities (proteins, RNA, DNA, ligands) defining the target complex.

        - `ProteinEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "protein"`

            - `"protein"`

          - `value: string`

            Amino acid sequence (one-letter codes)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Post-translational modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `RnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "rna"`

            - `"rna"`

          - `value: string`

            RNA nucleotide sequence (A, C, G, U, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Chemical modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `DnaEntityResponse = object { chain_ids, type, value, 2 more }`

          - `chain_ids: array of string`

            Chain IDs for this entity

          - `type: "dna"`

            - `"dna"`

          - `value: string`

            DNA nucleotide sequence (A, C, G, T, N)

          - `cyclic: optional boolean`

            Whether the sequence is cyclic

          - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

            Chemical modifications. Optional; defaults to an empty list when omitted.

            - `CcdModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "ccd"`

                - `"ccd"`

              - `value: string`

                CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

            - `SmilesModificationResponse = object { residue_index, type, value }`

              - `residue_index: number`

                0-based index of the residue to modify

              - `type: "smiles"`

                - `"smiles"`

              - `value: string`

                SMILES string for the modification

        - `LigandCcdEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs for this ligand

          - `type: "ligand_ccd"`

            - `"ligand_ccd"`

          - `value: string`

            CCD code (e.g., ATP, ADP)

        - `LigandSmilesEntityResponse = object { chain_ids, type, value }`

          - `chain_ids: array of string`

            Chain IDs for this ligand

          - `type: "ligand_smiles"`

            - `"ligand_smiles"`

          - `value: string`

            SMILES string representing the ligand

      - `type: "no_template"`

        - `"no_template"`

      - `bonds: optional array of object { atom1, atom2 }`

        Covalent bond constraints between atoms in the target complex. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

        - `atom1: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

        - `atom2: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `LigandAtomResponse = object { atom_name, chain_id, type }`

            Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID containing the atom

            - `type: "ligand_atom"`

              - `"ligand_atom"`

          - `PolymerAtomResponse = object { atom_name, chain_id, residue_index, type }`

            - `atom_name: string`

              Standardized atom name (verifiable in CIF file on RCSB)

            - `chain_id: string`

              Chain ID containing the atom

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_atom"`

              - `"polymer_atom"`

      - `constraints: optional array of object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }  or object { max_distance_angstrom, token1, token2, 2 more }`

        Structural constraints (pocket and contact). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

        - `PocketConstraintResponse = object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }`

          Constrains the binder to interact with specific pocket residues on the target.

          - `binder_chain_id: string`

            Chain ID of the binder molecule

          - `contact_residues: map[array of number]`

            Binding pocket residues keyed by chain ID. Each key is a chain ID (e.g. "A") and the value is an array of 0-indexed residue indices that define the pocket on that chain.

          - `max_distance_angstrom: number`

            Maximum allowed distance in Angstroms between binder and pocket residues. Typical range: 4-8 A.

          - `type: "pocket"`

            - `"pocket"`

          - `force: optional boolean`

            Whether to force the constraint

        - `ContactConstraintResponse = object { max_distance_angstrom, token1, token2, 2 more }`

          Contact constraint between two tokens. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `max_distance_angstrom: number`

            Maximum distance in Angstroms

          - `token1: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `PolymerContactTokenResponse = object { chain_id, residue_index, type }`

              - `chain_id: string`

                Chain ID

              - `residue_index: number`

                0-based residue index

              - `type: "polymer_contact"`

                - `"polymer_contact"`

            - `LigandContactTokenResponse = object { atom_name, chain_id, type }`

              Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

              - `atom_name: string`

                Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

              - `chain_id: string`

                Chain ID

              - `type: "ligand_contact"`

                - `"ligand_contact"`

          - `token2: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `PolymerContactTokenResponse = object { chain_id, residue_index, type }`

              - `chain_id: string`

                Chain ID

              - `residue_index: number`

                0-based residue index

              - `type: "polymer_contact"`

                - `"polymer_contact"`

            - `LigandContactTokenResponse = object { atom_name, chain_id, type }`

              Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

              - `atom_name: string`

                Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

              - `chain_id: string`

                Chain ID

              - `type: "ligand_contact"`

                - `"ligand_contact"`

          - `type: "contact"`

            - `"contact"`

          - `force: optional boolean`

            Whether to force the constraint

      - `epitope_ligand_chains: optional array of string`

        Chain IDs of ligand entities that are part of the binding epitope. Ligands are marked as epitope in full (no residue-level selection).

      - `epitope_residues: optional map[array of number]`

        Polymer chain residues where binder contact is desired (the epitope). Each key is a chain ID of a polymer entity, each value is an array of 0-indexed residue indices.

- `livemode: boolean`

  Whether this resource was created with a live API key.

- `progress: object { num_proteins_failed, num_proteins_screened, total_proteins_to_screen, latest_result_id }`

  - `num_proteins_failed: number`

    Number of accepted proteins that reached terminal failure during screening.

  - `num_proteins_screened: number`

    Number of accepted proteins that produced usable screening results.

  - `total_proteins_to_screen: number`

    Total number of proteins accepted into the screening run.

  - `latest_result_id: optional string`

    ID of the latest result

- `started_at: string`

- `status: "pending" or "running" or "succeeded" or 2 more`

  - `"pending"`

  - `"running"`

  - `"succeeded"`

  - `"failed"`

  - `"stopped"`

- `stopped_at: string`

- `workspace_id: string`

  Workspace ID

- `idempotency_key: optional string`

  Client-provided idempotency key

### Example

```http
curl https://api.boltz.bio/compute/v1/protein/library-screen/$ID/stop \
    -X POST \
    -H "x-api-key: $BOLTZ_API_KEY"
```

## Delete Data

**post** `/compute/v1/protein/library-screen/{id}/delete-data`

Permanently delete the input, output, and result data associated with this library screen. The library screen record itself is retained with a `data_deleted_at` timestamp. This action is irreversible.

### Path Parameters

- `id: string`

### Returns

- `id: string`

  ID of the resource whose data was deleted

- `data_deleted: true`

  - `true`

- `data_deleted_at: string`

  When the data was deleted

### Example

```http
curl https://api.boltz.bio/compute/v1/protein/library-screen/$ID/delete-data \
    -X POST \
    -H "x-api-key: $BOLTZ_API_KEY"
```

## Estimate Cost

**post** `/compute/v1/protein/library-screen/estimate-cost`

Estimate the cost of a protein library screen without creating any resource or consuming GPU.

### Body Parameters

- `proteins: array of object { entities, id }`

  List of protein entries to screen.

  - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 2 more`

    Entities that make up this protein complex

    - `ProteinEntity = object { chain_ids, type, value, 2 more }`

      - `chain_ids: array of string`

        Chain IDs for this entity

      - `type: "protein"`

        - `"protein"`

      - `value: string`

        Amino acid sequence (one-letter codes)

      - `cyclic: optional boolean`

        Whether the sequence is cyclic

      - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

        Post-translational modifications. Optional; defaults to an empty list when omitted.

        - `CcdModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "ccd"`

            - `"ccd"`

          - `value: string`

            CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

        - `SmilesModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "smiles"`

            - `"smiles"`

          - `value: string`

            SMILES string for the modification

    - `RnaEntity = object { chain_ids, type, value, 2 more }`

      - `chain_ids: array of string`

        Chain IDs for this entity

      - `type: "rna"`

        - `"rna"`

      - `value: string`

        RNA nucleotide sequence (A, C, G, U, N)

      - `cyclic: optional boolean`

        Whether the sequence is cyclic

      - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

        Chemical modifications. Optional; defaults to an empty list when omitted.

        - `CcdModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "ccd"`

            - `"ccd"`

          - `value: string`

            CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

        - `SmilesModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "smiles"`

            - `"smiles"`

          - `value: string`

            SMILES string for the modification

    - `DnaEntity = object { chain_ids, type, value, 2 more }`

      - `chain_ids: array of string`

        Chain IDs for this entity

      - `type: "dna"`

        - `"dna"`

      - `value: string`

        DNA nucleotide sequence (A, C, G, T, N)

      - `cyclic: optional boolean`

        Whether the sequence is cyclic

      - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

        Chemical modifications. Optional; defaults to an empty list when omitted.

        - `CcdModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "ccd"`

            - `"ccd"`

          - `value: string`

            CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

        - `SmilesModification = object { residue_index, type, value }`

          - `residue_index: number`

            0-based index of the residue to modify

          - `type: "smiles"`

            - `"smiles"`

          - `value: string`

            SMILES string for the modification

    - `LigandCcdEntity = object { chain_ids, type, value }`

      - `chain_ids: array of string`

        Chain IDs for this ligand

      - `type: "ligand_ccd"`

        - `"ligand_ccd"`

      - `value: string`

        CCD code (e.g., ATP, ADP)

    - `LigandSmilesEntity = object { chain_ids, type, value }`

      - `chain_ids: array of string`

        Chain IDs for this ligand

      - `type: "ligand_smiles"`

        - `"ligand_smiles"`

      - `value: string`

        SMILES string representing the ligand

  - `id: optional string`

    Optional client-provided identifier for this entry

- `target: object { chain_selection, structure, type }  or object { entities, type, bonds, 3 more }`

  Target specification (structure template or template-free)

  - `StructureTemplateTarget = object { chain_selection, structure, type }`

    Target defined by an uploaded 3D structure (CIF or PDB file). Only chains included in chain_selection are used.

    - `chain_selection: map[object { chain_type, crop_residues, epitope_residues, flexible_residues }  or object { chain_type } ]`

      Chains selected from the uploaded structure, keyed by chain ID. Only chains listed here are included in the engine run — any chains omitted from this mapping are ignored. Each value defines which residues to keep, which are epitope residues, and which are flexible.

      - `StructureTemplateTargetPolymerChainSpec = object { chain_type, crop_residues, epitope_residues, flexible_residues }`

        Per-chain specification for a polymer (protein/RNA/DNA) chain in a structure template target.

        - `chain_type: "polymer"`

          - `"polymer"`

        - `crop_residues: array of number or "all"`

          0-indexed residue indices to retain from this chain, or 'all' to keep all residues. Residues not listed are excluded from the engine run.

          - `UnionMember0 = array of number`

            0-indexed residue indices to keep

          - `UnionMember1 = "all"`

            - `"all"`

        - `epitope_residues: optional array of number`

          0-indexed residue indices where binder contact is desired (the epitope). All indices must be present in crop_residues.

        - `flexible_residues: optional array of number`

          0-indexed residue indices allowed to move during design (e.g. flexible loop regions). All indices must be present in crop_residues.

      - `StructureTemplateTargetLigandChainSpec = object { chain_type }`

        Per-chain specification for a ligand chain in a structure template target. The full ligand is always included.

        - `chain_type: "ligand"`

          - `"ligand"`

    - `structure: object { type, url }  or object { data, media_type, type }`

      How to provide a CIF structure file. URLs are auto-detected; base64 uploads must use chemical/x-cif media type.

      - `URLSource = object { type, url }`

        - `type: "url"`

          - `"url"`

        - `url: string`

      - `CifBase64Source = object { data, media_type, type }`

        - `data: string`

          Base64-encoded CIF file contents

        - `media_type: "chemical/x-cif"`

          Must be chemical/x-cif for CIF files

          - `"chemical/x-cif"`

        - `type: "base64"`

          - `"base64"`

    - `type: "structure_template"`

      - `"structure_template"`

  - `NoTemplateTarget = object { entities, type, bonds, 3 more }`

    Target defined by sequences only, without a 3D structure template

    - `entities: array of object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or object { chain_ids, type, value, 2 more }  or 2 more`

      Entities (proteins, RNA, DNA, ligands) defining the target complex.

      - `ProteinEntity = object { chain_ids, type, value, 2 more }`

        - `chain_ids: array of string`

          Chain IDs for this entity

        - `type: "protein"`

          - `"protein"`

        - `value: string`

          Amino acid sequence (one-letter codes)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Post-translational modifications. Optional; defaults to an empty list when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `RnaEntity = object { chain_ids, type, value, 2 more }`

        - `chain_ids: array of string`

          Chain IDs for this entity

        - `type: "rna"`

          - `"rna"`

        - `value: string`

          RNA nucleotide sequence (A, C, G, U, N)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Chemical modifications. Optional; defaults to an empty list when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `DnaEntity = object { chain_ids, type, value, 2 more }`

        - `chain_ids: array of string`

          Chain IDs for this entity

        - `type: "dna"`

          - `"dna"`

        - `value: string`

          DNA nucleotide sequence (A, C, G, T, N)

        - `cyclic: optional boolean`

          Whether the sequence is cyclic

        - `modifications: optional array of object { residue_index, type, value }  or object { residue_index, type, value }`

          Chemical modifications. Optional; defaults to an empty list when omitted.

          - `CcdModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "ccd"`

              - `"ccd"`

            - `value: string`

              CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

          - `SmilesModification = object { residue_index, type, value }`

            - `residue_index: number`

              0-based index of the residue to modify

            - `type: "smiles"`

              - `"smiles"`

            - `value: string`

              SMILES string for the modification

      - `LigandCcdEntity = object { chain_ids, type, value }`

        - `chain_ids: array of string`

          Chain IDs for this ligand

        - `type: "ligand_ccd"`

          - `"ligand_ccd"`

        - `value: string`

          CCD code (e.g., ATP, ADP)

      - `LigandSmilesEntity = object { chain_ids, type, value }`

        - `chain_ids: array of string`

          Chain IDs for this ligand

        - `type: "ligand_smiles"`

          - `"ligand_smiles"`

        - `value: string`

          SMILES string representing the ligand

    - `type: "no_template"`

      - `"no_template"`

    - `bonds: optional array of object { atom1, atom2 }`

      Covalent bond constraints between atoms in the target complex. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

      - `atom1: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

        Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

        - `LigandAtom = object { atom_name, chain_id, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

          - `chain_id: string`

            Chain ID containing the atom

          - `type: "ligand_atom"`

            - `"ligand_atom"`

        - `PolymerAtom = object { atom_name, chain_id, residue_index, type }`

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB)

          - `chain_id: string`

            Chain ID containing the atom

          - `residue_index: number`

            0-based residue index

          - `type: "polymer_atom"`

            - `"polymer_atom"`

      - `atom2: object { atom_name, chain_id, type }  or object { atom_name, chain_id, residue_index, type }`

        Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

        - `LigandAtom = object { atom_name, chain_id, type }`

          Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

          - `chain_id: string`

            Chain ID containing the atom

          - `type: "ligand_atom"`

            - `"ligand_atom"`

        - `PolymerAtom = object { atom_name, chain_id, residue_index, type }`

          - `atom_name: string`

            Standardized atom name (verifiable in CIF file on RCSB)

          - `chain_id: string`

            Chain ID containing the atom

          - `residue_index: number`

            0-based residue index

          - `type: "polymer_atom"`

            - `"polymer_atom"`

    - `constraints: optional array of object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }  or object { max_distance_angstrom, token1, token2, 2 more }`

      Structural constraints (pocket and contact). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

      - `PocketConstraint = object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }`

        Constrains the binder to interact with specific pocket residues on the target.

        - `binder_chain_id: string`

          Chain ID of the binder molecule

        - `contact_residues: map[array of number]`

          Binding pocket residues keyed by chain ID. Each key is a chain ID (e.g. "A") and the value is an array of 0-indexed residue indices that define the pocket on that chain.

        - `max_distance_angstrom: number`

          Maximum allowed distance in Angstroms between binder and pocket residues. Typical range: 4-8 A.

        - `type: "pocket"`

          - `"pocket"`

        - `force: optional boolean`

          Whether to force the constraint

      - `ContactConstraint = object { max_distance_angstrom, token1, token2, 2 more }`

        Contact constraint between two tokens. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

        - `max_distance_angstrom: number`

          Maximum distance in Angstroms

        - `token1: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

          Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `PolymerContactToken = object { chain_id, residue_index, type }`

            - `chain_id: string`

              Chain ID

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_contact"`

              - `"polymer_contact"`

          - `LigandContactToken = object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID

            - `type: "ligand_contact"`

              - `"ligand_contact"`

        - `token2: object { chain_id, residue_index, type }  or object { atom_name, chain_id, type }`

          Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

          - `PolymerContactToken = object { chain_id, residue_index, type }`

            - `chain_id: string`

              Chain ID

            - `residue_index: number`

              0-based residue index

            - `type: "polymer_contact"`

              - `"polymer_contact"`

          - `LigandContactToken = object { atom_name, chain_id, type }`

            Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

            - `atom_name: string`

              Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

            - `chain_id: string`

              Chain ID

            - `type: "ligand_contact"`

              - `"ligand_contact"`

        - `type: "contact"`

          - `"contact"`

        - `force: optional boolean`

          Whether to force the constraint

    - `epitope_ligand_chains: optional array of string`

      Chain IDs of ligand entities that are part of the binding epitope. Ligands are marked as epitope in full (no residue-level selection).

    - `epitope_residues: optional map[array of number]`

      Polymer chain residues where binder contact is desired (the epitope). Each key is a chain ID of a polymer entity, each value is an array of 0-indexed residue indices.

- `idempotency_key: optional string`

  Client-provided key to prevent duplicate submissions on retries

- `workspace_id: optional string`

  Target workspace ID (admin keys only; ignored for workspace keys)

### Returns

- `breakdown: object { application, cost_per_unit_usd, num_units }`

  Cost breakdown for the billed application.

  - `application: "structure_and_binding" or "small_molecule_design" or "small_molecule_library_screen" or 3 more`

    - `"structure_and_binding"`

    - `"small_molecule_design"`

    - `"small_molecule_library_screen"`

    - `"protein_design"`

    - `"protein_library_screen"`

    - `"adme"`

  - `cost_per_unit_usd: string`

    Estimated cost per displayed unit as a decimal string, rounded up to 4 decimal places. This may include token-size multipliers or generation overhead; estimated_cost_usd is the authoritative total.

  - `num_units: number`

    Number of units shown for the estimate. For structure-and-binding, this is the requested number of samples. For protein and small-molecule design/screen endpoints, this is the requested number of proteins or molecules.

- `disclaimer: string`

- `estimated_cost_usd: string`

  Estimated total cost as a decimal string

### Example

```http
curl https://api.boltz.bio/compute/v1/protein/library-screen/estimate-cost \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $BOLTZ_API_KEY" \
    -d '{
          "proteins": [
            {
              "entities": [
                {
                  "chain_ids": [
                    "string"
                  ],
                  "type": "protein",
                  "value": "value"
                }
              ]
            }
          ],
          "target": {
            "chain_selection": {
              "A": {
                "chain_type": "polymer",
                "crop_residues": [
                  0,
                  1,
                  2,
                  3,
                  4,
                  5,
                  6,
                  7,
                  8,
                  9,
                  10,
                  11,
                  12
                ],
                "epitope_residues": [
                  10,
                  11,
                  12
                ],
                "flexible_residues": [
                  5,
                  6,
                  7
                ]
              }
            },
            "structure": {
              "type": "url",
              "url": "https://example.com"
            },
            "type": "structure_template"
          }
        }'
```