boltz-api 0.38.0 → 0.39.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.39.1 (2026-05-27)
+
+Full Changelog: [v0.39.0...v0.39.1](https://github.com/boltz-bio/boltz-api-typescript/compare/v0.39.0...v0.39.1)
+
+### Documentation
+
+* document structure templates and custom MSA ([56e6c0b](https://github.com/boltz-bio/boltz-api-typescript/commit/56e6c0b0f11344fe5c7ccf725cd8a70a56054e7d))
+
+## 0.39.0 (2026-05-27)
+
+Full Changelog: [v0.38.0...v0.39.0](https://github.com/boltz-bio/boltz-api-typescript/compare/v0.38.0...v0.39.0)
+
+### Features
+
+* [codex] Add custom MSA support to structure predictions ([ad27bf1](https://github.com/boltz-bio/boltz-api-typescript/commit/ad27bf1985e4845897b0b51e64a6b02a540a2201))
+
 ## 0.38.0 (2026-05-26)
 
 Full Changelog: [v0.37.1...v0.38.0](https://github.com/boltz-bio/boltz-api-typescript/compare/v0.37.1...v0.38.0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "boltz-api",
-  "version": "0.38.0",
+  "version": "0.39.1",
   "description": "The official TypeScript library for the Boltz API",
   "author": "Boltz <contact@boltz.bio>",
   "types": "./index.d.ts",

package/resources/predictions/structure-and-binding.d.mts

@@ -3,7 +3,7 @@ import { APIPromise } from "../../core/api-promise.mjs";
 import { CursorPage, type CursorPageParams, PagePromise } from "../../core/pagination.mjs";
 import { RequestOptions } from "../../internal/request-options.mjs";
 /**
- * Predict 3D structure coordinates, per-residue confidence scores, and binding metrics for a molecular complex.
+ * Predict 3D structure coordinates, per-residue confidence scores, and binding metrics for a molecular complex. Supports optional template-guided folding and per-protein MSA control.
  */
 export declare class StructureAndBinding extends APIResource {
     /**
@@ -70,7 +70,10 @@ export declare class StructureAndBinding extends APIResource {
     estimateCost(body: StructureAndBindingEstimateCostParams, options?: RequestOptions): APIPromise<StructureAndBindingEstimateCostResponse>;
     /**
      * Submit a prediction job that produces 3D structure coordinates and confidence
-     * scores for the input molecular complex, with optional binding metrics.
+     * scores for the input molecular complex, with optional binding metrics. Protein
+     * entities can use automatic MSA generation, custom A3M/CSV MSAs, or empty MSA
+     * mode. Boltz-2.1 predictions can also include up to 4 CIF or PDB templates to
+     * guide protein-chain geometry.
      *
      * @example
      * ```ts
@@ -169,7 +172,7 @@ export declare namespace StructureAndBindingRetrieveResponse {
          * Entities (proteins, RNA, DNA, ligands) forming the complex to predict. Order
          * determines chain assignment.
          */
-        entities: Array<Input.ProteinEntityResponse | Input.RnaEntityResponse | Input.DnaEntityResponse | Input.LigandCcdEntityResponse | Input.LigandSmilesEntityResponse>;
+        entities: Array<Input.Boltz2ProteinEntityResponse | Input.RnaEntityResponse | Input.DnaEntityResponse | Input.LigandCcdEntityResponse | Input.LigandSmilesEntityResponse>;
         binding?: Input.LigandProteinBindingResponse | Input.ProteinProteinBindingResponse;
         /**
          * Bond constraints between atoms. Atom-level ligand references currently support
@@ -188,12 +191,14 @@ export declare namespace StructureAndBindingRetrieveResponse {
         num_samples?: number;
         /**
          * Template structure files to guide protein-chain prediction. Supports up to 4 CIF
-         * or PDB templates from HTTPS URLs or base64 uploads.
+         * or PDB templates from HTTPS URLs or base64 uploads. Use chain_id and template_id
+         * to map request chains to template chains when the IDs differ or when providing
+         * multi-chain templates.
          */
         templates?: Array<Input.Template>;
     }
     namespace Input {
-        interface ProteinEntityResponse {
+        interface Boltz2ProteinEntityResponse {
             /**
              * Chain IDs for this entity
              */
@@ -211,9 +216,16 @@ export declare namespace StructureAndBindingRetrieveResponse {
              * Post-translational modifications. Optional; defaults to an empty list when
              * omitted.
              */
-            modifications?: Array<ProteinEntityResponse.Modification>;
+            modifications?: Array<Boltz2ProteinEntityResponse.Modification>;
+            /**
+             * Optional protein MSA control. Omit msa on all protein entities to use automatic
+             * MSA generation. Use custom for user-provided A3M/CSV files, or empty for
+             * single-sequence mode. Custom MSA and automatic MSA cannot be mixed in one
+             * request.
+             */
+            msa?: Boltz2ProteinEntityResponse.Boltz2CustomMsaResponse | Boltz2ProteinEntityResponse.Boltz2EmptyMsaResponse;
         }
-        namespace ProteinEntityResponse {
+        namespace Boltz2ProteinEntityResponse {
             interface Modification {
                 /**
                  * 0-based index of the residue to modify
@@ -226,6 +238,40 @@ export declare namespace StructureAndBindingRetrieveResponse {
                  */
                 value: string;
             }
+            /**
+             * Use a user-provided MSA for this protein entity. If any protein entity uses a
+             * custom MSA, every other protein entity must use either custom or empty MSA;
+             * automatic MSA generation cannot be mixed with custom MSAs in the same request.
+             */
+            interface Boltz2CustomMsaResponse {
+                /**
+                 * Custom MSA file format. Base64 uploads must use media_type text/x-a3m for A3M or
+                 * text/csv for CSV.
+                 */
+                format: 'a3m' | 'csv';
+                source: Boltz2CustomMsaResponse.Source;
+                type: 'custom';
+            }
+            namespace Boltz2CustomMsaResponse {
+                interface Source {
+                    /**
+                     * URL to download the file
+                     */
+                    url: string;
+                    /**
+                     * When the presigned URL expires
+                     */
+                    url_expires_at: string;
+                }
+            }
+            /**
+             * Run this protein entity in single-sequence mode without an MSA. Use this for
+             * chains that should not use automatic MSA generation, including non-homologous
+             * chains in a request that also includes custom MSAs.
+             */
+            interface Boltz2EmptyMsaResponse {
+                type: 'empty';
+            }
         }
         interface RnaEntityResponse {
             /**
@@ -533,14 +579,21 @@ export declare namespace StructureAndBindingRetrieveResponse {
              */
             step_scale?: number;
         }
+        /**
+         * Template structure used as an inference-time guide for Boltz-2.1 protein-chain
+         * geometry. Provide a CIF or PDB file from an HTTPS URL or base64 upload.
+         */
         interface Template {
             /**
-             * Template structure format. Base64 sources must use a matching media_type.
+             * Template structure format. Base64 uploads must use media_type chemical/x-cif for
+             * CIF or chemical/x-pdb for PDB.
              */
             format: 'cif' | 'pdb';
             source: Template.Source;
             /**
-             * One query/template chain ID, or an ordered list of chain IDs.
+             * One chain ID, or an ordered list of chain IDs for multi-chain templates. For
+             * chain_id, values refer to input chains; for template_id, values refer to chains
+             * in the template file.
              */
             chain_id?: string | Array<string>;
             /**
@@ -548,7 +601,9 @@ export declare namespace StructureAndBindingRetrieveResponse {
              */
             force?: boolean;
             /**
-             * One query/template chain ID, or an ordered list of chain IDs.
+             * One chain ID, or an ordered list of chain IDs for multi-chain templates. For
+             * chain_id, values refer to input chains; for template_id, values refer to chains
+             * in the template file.
              */
             template_id?: string | Array<string>;
             /**
@@ -906,7 +961,7 @@ export declare namespace StructureAndBindingStartResponse {
          * Entities (proteins, RNA, DNA, ligands) forming the complex to predict. Order
          * determines chain assignment.
          */
-        entities: Array<Input.ProteinEntityResponse | Input.RnaEntityResponse | Input.DnaEntityResponse | Input.LigandCcdEntityResponse | Input.LigandSmilesEntityResponse>;
+        entities: Array<Input.Boltz2ProteinEntityResponse | Input.RnaEntityResponse | Input.DnaEntityResponse | Input.LigandCcdEntityResponse | Input.LigandSmilesEntityResponse>;
         binding?: Input.LigandProteinBindingResponse | Input.ProteinProteinBindingResponse;
         /**
          * Bond constraints between atoms. Atom-level ligand references currently support
@@ -925,12 +980,14 @@ export declare namespace StructureAndBindingStartResponse {
         num_samples?: number;
         /**
          * Template structure files to guide protein-chain prediction. Supports up to 4 CIF
-         * or PDB templates from HTTPS URLs or base64 uploads.
+         * or PDB templates from HTTPS URLs or base64 uploads. Use chain_id and template_id
+         * to map request chains to template chains when the IDs differ or when providing
+         * multi-chain templates.
          */
         templates?: Array<Input.Template>;
     }
     namespace Input {
-        interface ProteinEntityResponse {
+        interface Boltz2ProteinEntityResponse {
             /**
              * Chain IDs for this entity
              */
@@ -948,9 +1005,16 @@ export declare namespace StructureAndBindingStartResponse {
              * Post-translational modifications. Optional; defaults to an empty list when
              * omitted.
              */
-            modifications?: Array<ProteinEntityResponse.Modification>;
+            modifications?: Array<Boltz2ProteinEntityResponse.Modification>;
+            /**
+             * Optional protein MSA control. Omit msa on all protein entities to use automatic
+             * MSA generation. Use custom for user-provided A3M/CSV files, or empty for
+             * single-sequence mode. Custom MSA and automatic MSA cannot be mixed in one
+             * request.
+             */
+            msa?: Boltz2ProteinEntityResponse.Boltz2CustomMsaResponse | Boltz2ProteinEntityResponse.Boltz2EmptyMsaResponse;
         }
-        namespace ProteinEntityResponse {
+        namespace Boltz2ProteinEntityResponse {
             interface Modification {
                 /**
                  * 0-based index of the residue to modify
@@ -963,6 +1027,40 @@ export declare namespace StructureAndBindingStartResponse {
                  */
                 value: string;
             }
+            /**
+             * Use a user-provided MSA for this protein entity. If any protein entity uses a
+             * custom MSA, every other protein entity must use either custom or empty MSA;
+             * automatic MSA generation cannot be mixed with custom MSAs in the same request.
+             */
+            interface Boltz2CustomMsaResponse {
+                /**
+                 * Custom MSA file format. Base64 uploads must use media_type text/x-a3m for A3M or
+                 * text/csv for CSV.
+                 */
+                format: 'a3m' | 'csv';
+                source: Boltz2CustomMsaResponse.Source;
+                type: 'custom';
+            }
+            namespace Boltz2CustomMsaResponse {
+                interface Source {
+                    /**
+                     * URL to download the file
+                     */
+                    url: string;
+                    /**
+                     * When the presigned URL expires
+                     */
+                    url_expires_at: string;
+                }
+            }
+            /**
+             * Run this protein entity in single-sequence mode without an MSA. Use this for
+             * chains that should not use automatic MSA generation, including non-homologous
+             * chains in a request that also includes custom MSAs.
+             */
+            interface Boltz2EmptyMsaResponse {
+                type: 'empty';
+            }
         }
         interface RnaEntityResponse {
             /**
@@ -1270,14 +1368,21 @@ export declare namespace StructureAndBindingStartResponse {
              */
             step_scale?: number;
         }
+        /**
+         * Template structure used as an inference-time guide for Boltz-2.1 protein-chain
+         * geometry. Provide a CIF or PDB file from an HTTPS URL or base64 upload.
+         */
         interface Template {
             /**
-             * Template structure format. Base64 sources must use a matching media_type.
+             * Template structure format. Base64 uploads must use media_type chemical/x-cif for
+             * CIF or chemical/x-pdb for PDB.
              */
             format: 'cif' | 'pdb';
             source: Template.Source;
             /**
-             * One query/template chain ID, or an ordered list of chain IDs.
+             * One chain ID, or an ordered list of chain IDs for multi-chain templates. For
+             * chain_id, values refer to input chains; for template_id, values refer to chains
+             * in the template file.
              */
             chain_id?: string | Array<string>;
             /**
@@ -1285,7 +1390,9 @@ export declare namespace StructureAndBindingStartResponse {
              */
             force?: boolean;
             /**
-             * One query/template chain ID, or an ordered list of chain IDs.
+             * One chain ID, or an ordered list of chain IDs for multi-chain templates. For
+             * chain_id, values refer to input chains; for template_id, values refer to chains
+             * in the template file.
              */
             template_id?: string | Array<string>;
             /**
@@ -1494,7 +1601,7 @@ export declare namespace StructureAndBindingEstimateCostParams {
          * Entities (proteins, RNA, DNA, ligands) forming the complex to predict. Order
          * determines chain assignment.
          */
-        entities: Array<Input.ProteinEntity | Input.RnaEntity | Input.DnaEntity | Input.LigandCcdEntity | Input.LigandSmilesEntity>;
+        entities: Array<Input.Boltz2ProteinEntity | Input.RnaEntity | Input.DnaEntity | Input.LigandCcdEntity | Input.LigandSmilesEntity>;
         binding?: Input.LigandProteinBinding | Input.ProteinProteinBinding;
         /**
          * Bond constraints between atoms. Atom-level ligand references currently support
@@ -1513,12 +1620,14 @@ export declare namespace StructureAndBindingEstimateCostParams {
         num_samples?: number;
         /**
          * Template structure files to guide protein-chain prediction. Supports up to 4 CIF
-         * or PDB templates from HTTPS URLs or base64 uploads.
+         * or PDB templates from HTTPS URLs or base64 uploads. Use chain_id and template_id
+         * to map request chains to template chains when the IDs differ or when providing
+         * multi-chain templates.
          */
         templates?: Array<Input.Template>;
     }
     namespace Input {
-        interface ProteinEntity {
+        interface Boltz2ProteinEntity {
             /**
              * Chain IDs for this entity
              */
@@ -1536,9 +1645,16 @@ export declare namespace StructureAndBindingEstimateCostParams {
              * Post-translational modifications. Optional; defaults to an empty list when
              * omitted.
              */
-            modifications?: Array<ProteinEntity.Modification>;
+            modifications?: Array<Boltz2ProteinEntity.Modification>;
+            /**
+             * Optional protein MSA control. Omit msa on all protein entities to use automatic
+             * MSA generation. Use custom for user-provided A3M/CSV files, or empty for
+             * single-sequence mode. Custom MSA and automatic MSA cannot be mixed in one
+             * request.
+             */
+            msa?: Boltz2ProteinEntity.Boltz2CustomMsa | Boltz2ProteinEntity.Boltz2EmptyMsa;
         }
-        namespace ProteinEntity {
+        namespace Boltz2ProteinEntity {
             interface Modification {
                 /**
                  * 0-based index of the residue to modify
@@ -1551,6 +1667,48 @@ export declare namespace StructureAndBindingEstimateCostParams {
                  */
                 value: string;
             }
+            /**
+             * Use a user-provided MSA for this protein entity. If any protein entity uses a
+             * custom MSA, every other protein entity must use either custom or empty MSA;
+             * automatic MSA generation cannot be mixed with custom MSAs in the same request.
+             */
+            interface Boltz2CustomMsa {
+                /**
+                 * Custom MSA file format. Base64 uploads must use media_type text/x-a3m for A3M or
+                 * text/csv for CSV.
+                 */
+                format: 'a3m' | 'csv';
+                /**
+                 * How to provide a file to the API
+                 */
+                source: Boltz2CustomMsa.URLSource | Boltz2CustomMsa.Base64Source;
+                type: 'custom';
+            }
+            namespace Boltz2CustomMsa {
+                interface URLSource {
+                    type: 'url';
+                    url: string;
+                }
+                interface Base64Source {
+                    /**
+                     * Base64-encoded file contents
+                     */
+                    data: string;
+                    /**
+                     * MIME type (e.g., text/csv)
+                     */
+                    media_type: string;
+                    type: 'base64';
+                }
+            }
+            /**
+             * Run this protein entity in single-sequence mode without an MSA. Use this for
+             * chains that should not use automatic MSA generation, including non-homologous
+             * chains in a request that also includes custom MSAs.
+             */
+            interface Boltz2EmptyMsa {
+                type: 'empty';
+            }
         }
         interface RnaEntity {
             /**
@@ -1858,9 +2016,14 @@ export declare namespace StructureAndBindingEstimateCostParams {
              */
             step_scale?: number;
         }
+        /**
+         * Template structure used as an inference-time guide for Boltz-2.1 protein-chain
+         * geometry. Provide a CIF or PDB file from an HTTPS URL or base64 upload.
+         */
         interface Template {
             /**
-             * Template structure format. Base64 sources must use a matching media_type.
+             * Template structure format. Base64 uploads must use media_type chemical/x-cif for
+             * CIF or chemical/x-pdb for PDB.
              */
             format: 'cif' | 'pdb';
             /**
@@ -1868,7 +2031,9 @@ export declare namespace StructureAndBindingEstimateCostParams {
              */
             source: Template.URLSource | Template.Base64Source;
             /**
-             * One query/template chain ID, or an ordered list of chain IDs.
+             * One chain ID, or an ordered list of chain IDs for multi-chain templates. For
+             * chain_id, values refer to input chains; for template_id, values refer to chains
+             * in the template file.
              */
             chain_id?: string | Array<string>;
             /**
@@ -1876,7 +2041,9 @@ export declare namespace StructureAndBindingEstimateCostParams {
              */
             force?: boolean;
             /**
-             * One query/template chain ID, or an ordered list of chain IDs.
+             * One chain ID, or an ordered list of chain IDs for multi-chain templates. For
+             * chain_id, values refer to input chains; for template_id, values refer to chains
+             * in the template file.
              */
             template_id?: string | Array<string>;
             /**
@@ -1924,7 +2091,7 @@ export declare namespace StructureAndBindingStartParams {
          * Entities (proteins, RNA, DNA, ligands) forming the complex to predict. Order
          * determines chain assignment.
          */
-        entities: Array<Input.ProteinEntity | Input.RnaEntity | Input.DnaEntity | Input.LigandCcdEntity | Input.LigandSmilesEntity>;
+        entities: Array<Input.Boltz2ProteinEntity | Input.RnaEntity | Input.DnaEntity | Input.LigandCcdEntity | Input.LigandSmilesEntity>;
         binding?: Input.LigandProteinBinding | Input.ProteinProteinBinding;
         /**
          * Bond constraints between atoms. Atom-level ligand references currently support
@@ -1943,12 +2110,14 @@ export declare namespace StructureAndBindingStartParams {
         num_samples?: number;
         /**
          * Template structure files to guide protein-chain prediction. Supports up to 4 CIF
-         * or PDB templates from HTTPS URLs or base64 uploads.
+         * or PDB templates from HTTPS URLs or base64 uploads. Use chain_id and template_id
+         * to map request chains to template chains when the IDs differ or when providing
+         * multi-chain templates.
          */
         templates?: Array<Input.Template>;
     }
     namespace Input {
-        interface ProteinEntity {
+        interface Boltz2ProteinEntity {
             /**
              * Chain IDs for this entity
              */
@@ -1966,9 +2135,16 @@ export declare namespace StructureAndBindingStartParams {
              * Post-translational modifications. Optional; defaults to an empty list when
              * omitted.
              */
-            modifications?: Array<ProteinEntity.Modification>;
+            modifications?: Array<Boltz2ProteinEntity.Modification>;
+            /**
+             * Optional protein MSA control. Omit msa on all protein entities to use automatic
+             * MSA generation. Use custom for user-provided A3M/CSV files, or empty for
+             * single-sequence mode. Custom MSA and automatic MSA cannot be mixed in one
+             * request.
+             */
+            msa?: Boltz2ProteinEntity.Boltz2CustomMsa | Boltz2ProteinEntity.Boltz2EmptyMsa;
         }
-        namespace ProteinEntity {
+        namespace Boltz2ProteinEntity {
             interface Modification {
                 /**
                  * 0-based index of the residue to modify
@@ -1981,6 +2157,48 @@ export declare namespace StructureAndBindingStartParams {
                  */
                 value: string;
             }
+            /**
+             * Use a user-provided MSA for this protein entity. If any protein entity uses a
+             * custom MSA, every other protein entity must use either custom or empty MSA;
+             * automatic MSA generation cannot be mixed with custom MSAs in the same request.
+             */
+            interface Boltz2CustomMsa {
+                /**
+                 * Custom MSA file format. Base64 uploads must use media_type text/x-a3m for A3M or
+                 * text/csv for CSV.
+                 */
+                format: 'a3m' | 'csv';
+                /**
+                 * How to provide a file to the API
+                 */
+                source: Boltz2CustomMsa.URLSource | Boltz2CustomMsa.Base64Source;
+                type: 'custom';
+            }
+            namespace Boltz2CustomMsa {
+                interface URLSource {
+                    type: 'url';
+                    url: string;
+                }
+                interface Base64Source {
+                    /**
+                     * Base64-encoded file contents
+                     */
+                    data: string;
+                    /**
+                     * MIME type (e.g., text/csv)
+                     */
+                    media_type: string;
+                    type: 'base64';
+                }
+            }
+            /**
+             * Run this protein entity in single-sequence mode without an MSA. Use this for
+             * chains that should not use automatic MSA generation, including non-homologous
+             * chains in a request that also includes custom MSAs.
+             */
+            interface Boltz2EmptyMsa {
+                type: 'empty';
+            }
         }
         interface RnaEntity {
             /**
@@ -2288,9 +2506,14 @@ export declare namespace StructureAndBindingStartParams {
              */
             step_scale?: number;
         }
+        /**
+         * Template structure used as an inference-time guide for Boltz-2.1 protein-chain
+         * geometry. Provide a CIF or PDB file from an HTTPS URL or base64 upload.
+         */
         interface Template {
             /**
-             * Template structure format. Base64 sources must use a matching media_type.
+             * Template structure format. Base64 uploads must use media_type chemical/x-cif for
+             * CIF or chemical/x-pdb for PDB.
              */
             format: 'cif' | 'pdb';
             /**
@@ -2298,7 +2521,9 @@ export declare namespace StructureAndBindingStartParams {
              */
             source: Template.URLSource | Template.Base64Source;
             /**
-             * One query/template chain ID, or an ordered list of chain IDs.
+             * One chain ID, or an ordered list of chain IDs for multi-chain templates. For
+             * chain_id, values refer to input chains; for template_id, values refer to chains
+             * in the template file.
              */
             chain_id?: string | Array<string>;
             /**
@@ -2306,7 +2531,9 @@ export declare namespace StructureAndBindingStartParams {
              */
             force?: boolean;
             /**
-             * One query/template chain ID, or an ordered list of chain IDs.
+             * One chain ID, or an ordered list of chain IDs for multi-chain templates. For
+             * chain_id, values refer to input chains; for template_id, values refer to chains
+             * in the template file.
              */
             template_id?: string | Array<string>;
             /**