# Predictions # Structure And Binding ## Start `client.predictions.structureAndBinding.start(StructureAndBindingStartParamsbody, RequestOptionsoptions?): StructureAndBindingStartResponse` **post** `/compute/v1/predictions/structure-and-binding` Submit a prediction job that produces 3D structure coordinates and confidence scores for the input molecular complex, with optional binding metrics. ### Parameters - `body: StructureAndBindingStartParams` - `input: Input` - `entities: Array` Entities (proteins, RNA, DNA, ligands) forming the complex to predict. Order determines chain assignment. - `ProteinEntity` - `chain_ids: Array` Chain IDs for this entity - `type: "protein"` - `"protein"` - `value: string` Amino acid sequence (one-letter codes) - `cyclic?: boolean` Whether the sequence is cyclic - `modifications?: Array` Post-translational modifications. Optional; defaults to an empty list when omitted. - `CcdModification` - `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` - `residue_index: number` 0-based index of the residue to modify - `type: "smiles"` - `"smiles"` - `value: string` SMILES string for the modification - `RnaEntity` - `chain_ids: Array` Chain IDs for this entity - `type: "rna"` - `"rna"` - `value: string` RNA nucleotide sequence (A, C, G, U, N) - `cyclic?: boolean` Whether the sequence is cyclic - `modifications?: Array` Chemical modifications. Optional; defaults to an empty list when omitted. - `CcdModification` - `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` - `residue_index: number` 0-based index of the residue to modify - `type: "smiles"` - `"smiles"` - `value: string` SMILES string for the modification - `DnaEntity` - `chain_ids: Array` Chain IDs for this entity - `type: "dna"` - `"dna"` - `value: string` DNA nucleotide sequence (A, C, G, T, N) - `cyclic?: boolean` Whether the sequence is cyclic - `modifications?: Array` Chemical modifications. Optional; defaults to an empty list when omitted. - `CcdModification` - `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` - `residue_index: number` 0-based index of the residue to modify - `type: "smiles"` - `"smiles"` - `value: string` SMILES string for the modification - `LigandCcdEntity` - `chain_ids: Array` Chain IDs for this ligand - `type: "ligand_ccd"` - `"ligand_ccd"` - `value: string` CCD code (e.g., ATP, ADP) - `LigandSmilesEntity` - `chain_ids: Array` Chain IDs for this ligand - `type: "ligand_smiles"` - `"ligand_smiles"` - `value: string` SMILES string representing the ligand - `binding?: LigandProteinBinding | ProteinProteinBinding` - `LigandProteinBinding` - `binder_chain_id: string` Chain ID of the ligand binder (must have exactly 1 copy, <50 atoms, and only ligands+proteins in entities) - `type: "ligand_protein_binding"` - `"ligand_protein_binding"` - `ProteinProteinBinding` - `binder_chain_ids: Array` Chain IDs of the protein binders - `type: "protein_protein_binding"` - `"protein_protein_binding"` - `bonds?: Array` Bond constraints between atoms. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported. - `atom1: LigandAtom | PolymerAtom` Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported. - `LigandAtom` 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` - `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: LigandAtom | PolymerAtom` Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported. - `LigandAtom` 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` - `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?: Array` Structural constraints (pocket and contact). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported. - `PocketConstraint` Constrains the binder to interact with specific pocket residues on the target. - `binder_chain_id: string` Chain ID of the binder molecule - `contact_residues: Record>` 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?: boolean` Whether to force the constraint - `ContactConstraint` 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: PolymerContactToken | LigandContactToken` Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported. - `PolymerContactToken` - `chain_id: string` Chain ID - `residue_index: number` 0-based residue index - `type: "polymer_contact"` - `"polymer_contact"` - `LigandContactToken` 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: PolymerContactToken | LigandContactToken` Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported. - `PolymerContactToken` - `chain_id: string` Chain ID - `residue_index: number` 0-based residue index - `type: "polymer_contact"` - `"polymer_contact"` - `LigandContactToken` 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?: boolean` Whether to force the constraint - `model_options?: ModelOptions` - `recycling_steps?: number` The number of recycling steps to use for prediction. Default is 3. - `sampling_steps?: number` The number of sampling steps to use for prediction. Default is 200. - `step_scale?: number` Diffusion step scale (temperature). Controls sampling diversity — higher values produce more varied structures. Default is 1.638. - `num_samples?: number` Number of structure samples to generate - `model: "boltz-2.1"` Model to use for prediction - `"boltz-2.1"` - `idempotency_key?: string` Client-provided key to prevent duplicate submissions on retries - `workspace_id?: string` Target workspace ID (admin keys only; ignored for workspace keys) ### Returns - `StructureAndBindingStartResponse` - `id: string` Unique prediction identifier - `completed_at: string | null` - `created_at: string` - `data_deleted_at: string | null` When the input/output data was deleted, or null if still available - `error: Error | null` Error details when failed - `code: string` Machine-readable error code - `message: string` Human-readable error message - `details?: unknown` Additional field-level error details keyed by input path, when available. - `expires_at: string | null` When this resource and its associated data will be permanently deleted. Null while still in progress. - `input: Input | null` Prediction input (null if data deleted) - `entities: Array` Entities (proteins, RNA, DNA, ligands) forming the complex to predict. Order determines chain assignment. - `ProteinEntityResponse` - `chain_ids: Array` Chain IDs for this entity - `type: "protein"` - `"protein"` - `value: string` Amino acid sequence (one-letter codes) - `cyclic?: boolean` Whether the sequence is cyclic - `modifications?: Array` Post-translational modifications. Optional; defaults to an empty list when omitted. - `CcdModificationResponse` - `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` - `residue_index: number` 0-based index of the residue to modify - `type: "smiles"` - `"smiles"` - `value: string` SMILES string for the modification - `RnaEntityResponse` - `chain_ids: Array` Chain IDs for this entity - `type: "rna"` - `"rna"` - `value: string` RNA nucleotide sequence (A, C, G, U, N) - `cyclic?: boolean` Whether the sequence is cyclic - `modifications?: Array` Chemical modifications. Optional; defaults to an empty list when omitted. - `CcdModificationResponse` - `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` - `residue_index: number` 0-based index of the residue to modify - `type: "smiles"` - `"smiles"` - `value: string` SMILES string for the modification - `DnaEntityResponse` - `chain_ids: Array` Chain IDs for this entity - `type: "dna"` - `"dna"` - `value: string` DNA nucleotide sequence (A, C, G, T, N) - `cyclic?: boolean` Whether the sequence is cyclic - `modifications?: Array` Chemical modifications. Optional; defaults to an empty list when omitted. - `CcdModificationResponse` - `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` - `residue_index: number` 0-based index of the residue to modify - `type: "smiles"` - `"smiles"` - `value: string` SMILES string for the modification - `LigandCcdEntityResponse` - `chain_ids: Array` Chain IDs for this ligand - `type: "ligand_ccd"` - `"ligand_ccd"` - `value: string` CCD code (e.g., ATP, ADP) - `LigandSmilesEntityResponse` - `chain_ids: Array` Chain IDs for this ligand - `type: "ligand_smiles"` - `"ligand_smiles"` - `value: string` SMILES string representing the ligand - `binding?: LigandProteinBindingResponse | ProteinProteinBindingResponse` - `LigandProteinBindingResponse` - `binder_chain_id: string` Chain ID of the ligand binder (must have exactly 1 copy, <50 atoms, and only ligands+proteins in entities) - `type: "ligand_protein_binding"` - `"ligand_protein_binding"` - `ProteinProteinBindingResponse` - `binder_chain_ids: Array` Chain IDs of the protein binders - `type: "protein_protein_binding"` - `"protein_protein_binding"` - `bonds?: Array` Bond constraints between atoms. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported. - `atom1: LigandAtomResponse | PolymerAtomResponse` Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported. - `LigandAtomResponse` 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` - `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: LigandAtomResponse | PolymerAtomResponse` Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported. - `LigandAtomResponse` 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` - `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?: Array` Structural constraints (pocket and contact). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported. - `PocketConstraintResponse` Constrains the binder to interact with specific pocket residues on the target. - `binder_chain_id: string` Chain ID of the binder molecule - `contact_residues: Record>` 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?: boolean` Whether to force the constraint - `ContactConstraintResponse` 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: PolymerContactTokenResponse | LigandContactTokenResponse` Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported. - `PolymerContactTokenResponse` - `chain_id: string` Chain ID - `residue_index: number` 0-based residue index - `type: "polymer_contact"` - `"polymer_contact"` - `LigandContactTokenResponse` 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: PolymerContactTokenResponse | LigandContactTokenResponse` Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported. - `PolymerContactTokenResponse` - `chain_id: string` Chain ID - `residue_index: number` 0-based residue index - `type: "polymer_contact"` - `"polymer_contact"` - `LigandContactTokenResponse` 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?: boolean` Whether to force the constraint - `model_options?: ModelOptions` - `recycling_steps?: number` The number of recycling steps to use for prediction. Default is 3. - `sampling_steps?: number` The number of sampling steps to use for prediction. Default is 200. - `step_scale?: number` Diffusion step scale (temperature). Controls sampling diversity — higher values produce more varied structures. Default is 1.638. - `num_samples?: number` Number of structure samples to generate - `livemode: boolean` Whether this resource was created with a live API key. - `model: "boltz-2.1"` Model used for prediction - `"boltz-2.1"` - `output: Output | null` Prediction output when succeeded - `all_sample_results: Array` Per-sample structure results - `metrics: Metrics` - `complex_ipde: number` Complex interface predicted distance error. Lower is better. - `complex_iplddt: number` Complex interface pLDDT (0-1 float). Confidence at inter-chain interfaces. - `complex_pde: number` Complex predicted distance error. Lower is better. - `complex_plddt: number` Complex pLDDT (0-1 float). Per-residue confidence averaged over the complex. - `iptm: number` Interface predicted TM score (0-1). Confidence in domain interfaces. - `ligand_iptm: number` Ligand interface pTM (0-1). Only present when ligands are included. - `protein_iptm: number` Protein-protein interface pTM (0-1). Only present for multi-protein complexes. - `ptm: number` Predicted TM score (0-1). Global structure quality. - `structure_confidence: number` Overall structure confidence (0-1). - `structure: Structure` - `url: string` URL to download the file - `url_expires_at: string` When the presigned URL expires - `best_sample: BestSample` - `metrics: Metrics` - `complex_ipde: number` Complex interface predicted distance error. Lower is better. - `complex_iplddt: number` Complex interface pLDDT (0-1 float). Confidence at inter-chain interfaces. - `complex_pde: number` Complex predicted distance error. Lower is better. - `complex_plddt: number` Complex pLDDT (0-1 float). Per-residue confidence averaged over the complex. - `iptm: number` Interface predicted TM score (0-1). Confidence in domain interfaces. - `ligand_iptm: number` Ligand interface pTM (0-1). Only present when ligands are included. - `protein_iptm: number` Protein-protein interface pTM (0-1). Only present for multi-protein complexes. - `ptm: number` Predicted TM score (0-1). Global structure quality. - `structure_confidence: number` Overall structure confidence (0-1). - `structure: Structure` - `url: string` URL to download the file - `url_expires_at: string` When the presigned URL expires - `archive?: Archive` - `url: string` URL to download the file - `url_expires_at: string` When the presigned URL expires - `binding_metrics?: LigandProteinBindingMetrics | ProteinProteinBindingMetrics` - `LigandProteinBindingMetrics` - `binding_confidence: number` Confidence that binding occurs (0-1). Primary metric for hit discovery. - `optimization_score: number` Binding strength ranking score for lead optimization. Higher values indicate stronger predicted binding. - `type: "ligand_protein_binding_metrics"` - `"ligand_protein_binding_metrics"` - `ProteinProteinBindingMetrics` - `binding_confidence: number` Confidence that binding occurs (0-1). Primary metric for hit discovery. - `type: "protein_protein_binding_metrics"` - `"protein_protein_binding_metrics"` - `started_at: string | null` - `status: "pending" | "running" | "succeeded" | "failed"` - `"pending"` - `"running"` - `"succeeded"` - `"failed"` - `version: string` Model version used for prediction - `workspace_id: string` Workspace ID - `idempotency_key?: string` Client-provided idempotency key ### Example ```typescript import Boltz from 'boltz-api'; const client = new Boltz({ apiKey: process.env['BOLTZ_API_KEY'], // This is the default and can be omitted }); const response = await client.predictions.structureAndBinding.start({ input: { entities: [ { chain_ids: ['string'], type: 'protein', value: 'value', }, ], }, model: 'boltz-2.1', }); console.log(response.id); ``` ## List `client.predictions.structureAndBinding.list(StructureAndBindingListParamsquery?, RequestOptionsoptions?): CursorPage` **get** `/compute/v1/predictions/structure-and-binding` List structure and binding predictions, optionally filtered by workspace ### Parameters - `query: StructureAndBindingListParams` - `after_id?: string` Return results after this ID - `before_id?: string` Return results before this ID - `limit?: number` Max items to return. Defaults to 100. - `workspace_id?: 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 - `StructureAndBindingListResponse` - `id: string` Unique prediction identifier - `completed_at: string | null` - `created_at: string` - `data_deleted_at: string | null` When the input/output data was deleted, or null if still available - `error: Error | null` Error details when failed - `code: string` Machine-readable error code - `message: string` Human-readable error message - `details?: unknown` Additional field-level error details keyed by input path, when available. - `expires_at: string | null` When this resource and its associated data will be permanently deleted. Null while still in progress. - `livemode: boolean` Whether this resource was created with a live API key. - `model: "boltz-2.1"` Model used for prediction - `"boltz-2.1"` - `started_at: string | null` - `status: "pending" | "running" | "succeeded" | "failed"` - `"pending"` - `"running"` - `"succeeded"` - `"failed"` - `version: string` Model version used for prediction - `workspace_id: string` Workspace ID - `idempotency_key?: string` Client-provided idempotency key ### Example ```typescript import Boltz from 'boltz-api'; const client = new Boltz({ apiKey: process.env['BOLTZ_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const structureAndBindingListResponse of client.predictions.structureAndBinding.list()) { console.log(structureAndBindingListResponse.id); } ``` ## Retrieve `client.predictions.structureAndBinding.retrieve(stringid, StructureAndBindingRetrieveParamsquery?, RequestOptionsoptions?): StructureAndBindingRetrieveResponse` **get** `/compute/v1/predictions/structure-and-binding/{id}` Retrieve a prediction by ID, including its status and results. ### Parameters - `id: string` - `query: StructureAndBindingRetrieveParams` - `workspace_id?: string` Workspace ID. Only used with admin API keys. Ignored (or validated) for workspace-scoped keys. ### Returns - `StructureAndBindingRetrieveResponse` - `id: string` Unique prediction identifier - `completed_at: string | null` - `created_at: string` - `data_deleted_at: string | null` When the input/output data was deleted, or null if still available - `error: Error | null` Error details when failed - `code: string` Machine-readable error code - `message: string` Human-readable error message - `details?: unknown` Additional field-level error details keyed by input path, when available. - `expires_at: string | null` When this resource and its associated data will be permanently deleted. Null while still in progress. - `input: Input | null` Prediction input (null if data deleted) - `entities: Array` Entities (proteins, RNA, DNA, ligands) forming the complex to predict. Order determines chain assignment. - `ProteinEntityResponse` - `chain_ids: Array` Chain IDs for this entity - `type: "protein"` - `"protein"` - `value: string` Amino acid sequence (one-letter codes) - `cyclic?: boolean` Whether the sequence is cyclic - `modifications?: Array` Post-translational modifications. Optional; defaults to an empty list when omitted. - `CcdModificationResponse` - `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` - `residue_index: number` 0-based index of the residue to modify - `type: "smiles"` - `"smiles"` - `value: string` SMILES string for the modification - `RnaEntityResponse` - `chain_ids: Array` Chain IDs for this entity - `type: "rna"` - `"rna"` - `value: string` RNA nucleotide sequence (A, C, G, U, N) - `cyclic?: boolean` Whether the sequence is cyclic - `modifications?: Array` Chemical modifications. Optional; defaults to an empty list when omitted. - `CcdModificationResponse` - `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` - `residue_index: number` 0-based index of the residue to modify - `type: "smiles"` - `"smiles"` - `value: string` SMILES string for the modification - `DnaEntityResponse` - `chain_ids: Array` Chain IDs for this entity - `type: "dna"` - `"dna"` - `value: string` DNA nucleotide sequence (A, C, G, T, N) - `cyclic?: boolean` Whether the sequence is cyclic - `modifications?: Array` Chemical modifications. Optional; defaults to an empty list when omitted. - `CcdModificationResponse` - `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` - `residue_index: number` 0-based index of the residue to modify - `type: "smiles"` - `"smiles"` - `value: string` SMILES string for the modification - `LigandCcdEntityResponse` - `chain_ids: Array` Chain IDs for this ligand - `type: "ligand_ccd"` - `"ligand_ccd"` - `value: string` CCD code (e.g., ATP, ADP) - `LigandSmilesEntityResponse` - `chain_ids: Array` Chain IDs for this ligand - `type: "ligand_smiles"` - `"ligand_smiles"` - `value: string` SMILES string representing the ligand - `binding?: LigandProteinBindingResponse | ProteinProteinBindingResponse` - `LigandProteinBindingResponse` - `binder_chain_id: string` Chain ID of the ligand binder (must have exactly 1 copy, <50 atoms, and only ligands+proteins in entities) - `type: "ligand_protein_binding"` - `"ligand_protein_binding"` - `ProteinProteinBindingResponse` - `binder_chain_ids: Array` Chain IDs of the protein binders - `type: "protein_protein_binding"` - `"protein_protein_binding"` - `bonds?: Array` Bond constraints between atoms. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported. - `atom1: LigandAtomResponse | PolymerAtomResponse` Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported. - `LigandAtomResponse` 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` - `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: LigandAtomResponse | PolymerAtomResponse` Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported. - `LigandAtomResponse` 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` - `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?: Array` Structural constraints (pocket and contact). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported. - `PocketConstraintResponse` Constrains the binder to interact with specific pocket residues on the target. - `binder_chain_id: string` Chain ID of the binder molecule - `contact_residues: Record>` 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?: boolean` Whether to force the constraint - `ContactConstraintResponse` 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: PolymerContactTokenResponse | LigandContactTokenResponse` Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported. - `PolymerContactTokenResponse` - `chain_id: string` Chain ID - `residue_index: number` 0-based residue index - `type: "polymer_contact"` - `"polymer_contact"` - `LigandContactTokenResponse` 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: PolymerContactTokenResponse | LigandContactTokenResponse` Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported. - `PolymerContactTokenResponse` - `chain_id: string` Chain ID - `residue_index: number` 0-based residue index - `type: "polymer_contact"` - `"polymer_contact"` - `LigandContactTokenResponse` 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?: boolean` Whether to force the constraint - `model_options?: ModelOptions` - `recycling_steps?: number` The number of recycling steps to use for prediction. Default is 3. - `sampling_steps?: number` The number of sampling steps to use for prediction. Default is 200. - `step_scale?: number` Diffusion step scale (temperature). Controls sampling diversity — higher values produce more varied structures. Default is 1.638. - `num_samples?: number` Number of structure samples to generate - `livemode: boolean` Whether this resource was created with a live API key. - `model: "boltz-2.1"` Model used for prediction - `"boltz-2.1"` - `output: Output | null` Prediction output when succeeded - `all_sample_results: Array` Per-sample structure results - `metrics: Metrics` - `complex_ipde: number` Complex interface predicted distance error. Lower is better. - `complex_iplddt: number` Complex interface pLDDT (0-1 float). Confidence at inter-chain interfaces. - `complex_pde: number` Complex predicted distance error. Lower is better. - `complex_plddt: number` Complex pLDDT (0-1 float). Per-residue confidence averaged over the complex. - `iptm: number` Interface predicted TM score (0-1). Confidence in domain interfaces. - `ligand_iptm: number` Ligand interface pTM (0-1). Only present when ligands are included. - `protein_iptm: number` Protein-protein interface pTM (0-1). Only present for multi-protein complexes. - `ptm: number` Predicted TM score (0-1). Global structure quality. - `structure_confidence: number` Overall structure confidence (0-1). - `structure: Structure` - `url: string` URL to download the file - `url_expires_at: string` When the presigned URL expires - `best_sample: BestSample` - `metrics: Metrics` - `complex_ipde: number` Complex interface predicted distance error. Lower is better. - `complex_iplddt: number` Complex interface pLDDT (0-1 float). Confidence at inter-chain interfaces. - `complex_pde: number` Complex predicted distance error. Lower is better. - `complex_plddt: number` Complex pLDDT (0-1 float). Per-residue confidence averaged over the complex. - `iptm: number` Interface predicted TM score (0-1). Confidence in domain interfaces. - `ligand_iptm: number` Ligand interface pTM (0-1). Only present when ligands are included. - `protein_iptm: number` Protein-protein interface pTM (0-1). Only present for multi-protein complexes. - `ptm: number` Predicted TM score (0-1). Global structure quality. - `structure_confidence: number` Overall structure confidence (0-1). - `structure: Structure` - `url: string` URL to download the file - `url_expires_at: string` When the presigned URL expires - `archive?: Archive` - `url: string` URL to download the file - `url_expires_at: string` When the presigned URL expires - `binding_metrics?: LigandProteinBindingMetrics | ProteinProteinBindingMetrics` - `LigandProteinBindingMetrics` - `binding_confidence: number` Confidence that binding occurs (0-1). Primary metric for hit discovery. - `optimization_score: number` Binding strength ranking score for lead optimization. Higher values indicate stronger predicted binding. - `type: "ligand_protein_binding_metrics"` - `"ligand_protein_binding_metrics"` - `ProteinProteinBindingMetrics` - `binding_confidence: number` Confidence that binding occurs (0-1). Primary metric for hit discovery. - `type: "protein_protein_binding_metrics"` - `"protein_protein_binding_metrics"` - `started_at: string | null` - `status: "pending" | "running" | "succeeded" | "failed"` - `"pending"` - `"running"` - `"succeeded"` - `"failed"` - `version: string` Model version used for prediction - `workspace_id: string` Workspace ID - `idempotency_key?: string` Client-provided idempotency key ### Example ```typescript import Boltz from 'boltz-api'; const client = new Boltz({ apiKey: process.env['BOLTZ_API_KEY'], // This is the default and can be omitted }); const structureAndBinding = await client.predictions.structureAndBinding.retrieve( 'sab_pred_2X7Ab9Cd3Ef6Gh1JkLmN', ); console.log(structureAndBinding.id); ``` ## Delete Data `client.predictions.structureAndBinding.deleteData(stringid, RequestOptionsoptions?): StructureAndBindingDeleteDataResponse` **post** `/compute/v1/predictions/structure-and-binding/{id}/delete-data` Permanently delete the input, output, and result data associated with this prediction. The prediction record itself is retained with a `data_deleted_at` timestamp. This action is irreversible. ### Parameters - `id: string` ### Returns - `StructureAndBindingDeleteDataResponse` - `id: string` ID of the resource whose data was deleted - `data_deleted: true` - `true` - `data_deleted_at: string` When the data was deleted ### Example ```typescript import Boltz from 'boltz-api'; const client = new Boltz({ apiKey: process.env['BOLTZ_API_KEY'], // This is the default and can be omitted }); const response = await client.predictions.structureAndBinding.deleteData( 'sab_pred_2X7Ab9Cd3Ef6Gh1JkLmN', ); console.log(response.id); ``` ## Estimate Cost `client.predictions.structureAndBinding.estimateCost(StructureAndBindingEstimateCostParamsbody, RequestOptionsoptions?): StructureAndBindingEstimateCostResponse` **post** `/compute/v1/predictions/structure-and-binding/estimate-cost` Estimate the cost of a prediction without creating any resource or consuming GPU. ### Parameters - `body: StructureAndBindingEstimateCostParams` - `input: Input` - `entities: Array` Entities (proteins, RNA, DNA, ligands) forming the complex to predict. Order determines chain assignment. - `ProteinEntity` - `chain_ids: Array` Chain IDs for this entity - `type: "protein"` - `"protein"` - `value: string` Amino acid sequence (one-letter codes) - `cyclic?: boolean` Whether the sequence is cyclic - `modifications?: Array` Post-translational modifications. Optional; defaults to an empty list when omitted. - `CcdModification` - `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` - `residue_index: number` 0-based index of the residue to modify - `type: "smiles"` - `"smiles"` - `value: string` SMILES string for the modification - `RnaEntity` - `chain_ids: Array` Chain IDs for this entity - `type: "rna"` - `"rna"` - `value: string` RNA nucleotide sequence (A, C, G, U, N) - `cyclic?: boolean` Whether the sequence is cyclic - `modifications?: Array` Chemical modifications. Optional; defaults to an empty list when omitted. - `CcdModification` - `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` - `residue_index: number` 0-based index of the residue to modify - `type: "smiles"` - `"smiles"` - `value: string` SMILES string for the modification - `DnaEntity` - `chain_ids: Array` Chain IDs for this entity - `type: "dna"` - `"dna"` - `value: string` DNA nucleotide sequence (A, C, G, T, N) - `cyclic?: boolean` Whether the sequence is cyclic - `modifications?: Array` Chemical modifications. Optional; defaults to an empty list when omitted. - `CcdModification` - `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` - `residue_index: number` 0-based index of the residue to modify - `type: "smiles"` - `"smiles"` - `value: string` SMILES string for the modification - `LigandCcdEntity` - `chain_ids: Array` Chain IDs for this ligand - `type: "ligand_ccd"` - `"ligand_ccd"` - `value: string` CCD code (e.g., ATP, ADP) - `LigandSmilesEntity` - `chain_ids: Array` Chain IDs for this ligand - `type: "ligand_smiles"` - `"ligand_smiles"` - `value: string` SMILES string representing the ligand - `binding?: LigandProteinBinding | ProteinProteinBinding` - `LigandProteinBinding` - `binder_chain_id: string` Chain ID of the ligand binder (must have exactly 1 copy, <50 atoms, and only ligands+proteins in entities) - `type: "ligand_protein_binding"` - `"ligand_protein_binding"` - `ProteinProteinBinding` - `binder_chain_ids: Array` Chain IDs of the protein binders - `type: "protein_protein_binding"` - `"protein_protein_binding"` - `bonds?: Array` Bond constraints between atoms. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported. - `atom1: LigandAtom | PolymerAtom` Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported. - `LigandAtom` 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` - `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: LigandAtom | PolymerAtom` Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported. - `LigandAtom` 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` - `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?: Array` Structural constraints (pocket and contact). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported. - `PocketConstraint` Constrains the binder to interact with specific pocket residues on the target. - `binder_chain_id: string` Chain ID of the binder molecule - `contact_residues: Record>` 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?: boolean` Whether to force the constraint - `ContactConstraint` 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: PolymerContactToken | LigandContactToken` Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported. - `PolymerContactToken` - `chain_id: string` Chain ID - `residue_index: number` 0-based residue index - `type: "polymer_contact"` - `"polymer_contact"` - `LigandContactToken` 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: PolymerContactToken | LigandContactToken` Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported. - `PolymerContactToken` - `chain_id: string` Chain ID - `residue_index: number` 0-based residue index - `type: "polymer_contact"` - `"polymer_contact"` - `LigandContactToken` 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?: boolean` Whether to force the constraint - `model_options?: ModelOptions` - `recycling_steps?: number` The number of recycling steps to use for prediction. Default is 3. - `sampling_steps?: number` The number of sampling steps to use for prediction. Default is 200. - `step_scale?: number` Diffusion step scale (temperature). Controls sampling diversity — higher values produce more varied structures. Default is 1.638. - `num_samples?: number` Number of structure samples to generate - `model: "boltz-2.1"` Model to use for prediction - `"boltz-2.1"` - `idempotency_key?: string` Client-provided key to prevent duplicate submissions on retries - `workspace_id?: string` Target workspace ID (admin keys only; ignored for workspace keys) ### Returns - `StructureAndBindingEstimateCostResponse` Estimate response with monetary values encoded as decimal strings to preserve precision. - `breakdown: Breakdown` Cost breakdown for the billed application. - `application: "structure_and_binding" | "small_molecule_design" | "small_molecule_library_screen" | 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 ```typescript import Boltz from 'boltz-api'; const client = new Boltz({ apiKey: process.env['BOLTZ_API_KEY'], // This is the default and can be omitted }); const response = await client.predictions.structureAndBinding.estimateCost({ input: { entities: [ { chain_ids: ['string'], type: 'protein', value: 'value', }, ], }, model: 'boltz-2.1', }); console.log(response.breakdown); ```