Redesign protein sequences

POST /compute/v1/protein/sequence-redesign takes exactly one CIF and redesigns selected protein residues while keeping the input chain structure fixed. Use it when you already have the complex or scaffold structure and want controlled redesign on top of fixed chain geometry.

Use POST /compute/v1/protein/design when you need de novo binder generation, a request-local template catalog, or mixed template-free and template-backed design entities.

Run

Start with start(), then poll retrieve() and list_results() or use the regular download-results flow when you want artifacts on disk.

Python

import os
from boltz_api import Boltz

client = Boltz(api_key=os.environ["BOLTZ_API_KEY"])

redesign = client.protein.sequence_redesign.start(
type="binder",
num_proteins=10,
structure={"type": "url", "url": "https://example.com/complex.cif"},
entities=[
{"type": "from_template", "chain_id": "A", "role": "target"},
{
"type": "from_template",
"chain_id": "B",
"role": "binder",
"design_motifs": [
{
"type": "residues",
"residues": [26, 27, 28, 29, 30],
"filters": [],
}
],
},
],
)

CLI

Write your request body to protein-sequence-redesign.json (see Input format), then:

RUN_ID=$(
  boltz-api --format raw protein:sequence-redesign start \
    --input @json://./protein-sequence-redesign.json | jq -r '.id'
)

boltz-api protein:sequence-redesign retrieve --id "$RUN_ID"
boltz-api protein:sequence-redesign list-results --id "$RUN_ID"

TypeScript

import Boltz from "boltz-api";

const client = new Boltz({ apiKey: process.env["BOLTZ_API_KEY"] });

const redesign = await client.protein.sequenceRedesign.start({
type: "binder",
num_proteins: 10,
structure: { type: "url", url: "https://example.com/complex.cif" },
entities: [
{ type: "from_template", chain_id: "A", role: "target" },
{
type: "from_template",
chain_id: "B",
role: "binder",
design_motifs: [
{
type: "residues",
residues: [26, 27, 28, 29, 30],
filters: [],
},
],
},
],
});

Input format

Sequence redesign uses one fixed CIF source, then assigns every chain in that structure exactly once.

request

BinderGeneric

Copy

{
  "type": "binder",
  "num_proteins": 10,
  "structure": { "type": "url", "url": "https://example.com/complex.cif" },
  "entities": [
    # every chain in the CIF must appear exactly once
    { "type": "from_template", "chain_id": "A", "role": "target" },
    {
      "type": "from_template",
      "chain_id": "B",
      "role": "binder",
      "design_motifs": [
        {
          "type": "residues",
          "residues": [26, 27, 28, 29, 30],
          "filters": [
            { "type": "excluded_sequence_motifs", "motifs": ["NXS"] }
          ]
        }
      ]
    },
    { "type": "from_template", "chain_id": "C", "role": "binder" }
  ]
  # omit "global_design_filters" to keep the default excluded_amino_acids:["C"]
}

• structure is a single CIF source, not a request-local template catalog.
• Every chain in that CIF must appear exactly once in entities. Missing, duplicated, or unknown chain IDs are rejected.
• global_design_filters applies to every redesigned region. Omit it to keep the default excluded_amino_acids: ["C"]; pass [] to disable global filters.

Binder mode (type: "binder")

Use binder mode for a fixed target/binder complex:

• Every entity includes role: "target" or role: "binder".
• You must provide at least one target chain and at least one binder chain.
• Only protein binder chains can carry design_motifs.
• Across binder protein chains, redesign at least five unique residues total.

Generic mode (type: "generic")

Use generic mode for scaffold-only sequence redesign:

• List every chain exactly once, without target/binder roles.
• At least one protein residue must be redesigned somewhere in the request.
• Generic runs use the same lifecycle and artifact model as binder runs, but they omit binding-specific metrics.

Residue motifs and filters

Each redesign motif is residue-based:

• type: "residues" takes a 0-indexed residue list on one protein chain.
• Residues cannot be duplicated, out of range, or overlapped across motifs on the same chain.
• filters stacks with global_design_filters, so you can tighten requirements for only one redesigned region.

Output format

Results use the same discriminated binder / generic result union as protein design. Binder runs include binding metrics; generic runs include only structure and secondary-structure metrics.

result type

BinderGeneric

Copy

{
  "data": [
    {
      "id": "pres_8f3a2b",
      "type": "binder",
      "created_at": "2026-07-14T12:14:19Z",
      "entities": [
        { "type": "protein", "chain_ids": ["A"], "value": "MKTIIALSYIFCLVFA" },
        { "type": "protein", "chain_ids": ["B"], "value": "QVQLVESGGGLVQPGGSLRLSCAASGFTFSS" }
      ],
      "metrics": {
        "binding_confidence": 0.84,
        "structure_confidence": 0.9,
        "iptm": 0.82,
        "min_interaction_pae": 5.2,
        "helix_fraction": 0.33,
        "sheet_fraction": 0.28,
        "loop_fraction": 0.39
      },
      "artifacts": {
        "structure": {
          "url": "https://.../structure.cif",
          "url_expires_at": "2026-07-14T13:14:19Z"
        },
        "archive": {
          "url": "https://.../archive.tar.gz",
          "url_expires_at": "2026-07-14T13:14:19Z"
        }
      },
      "warnings": []
    }
  ],
  "has_more": True,
  "first_id": "pres_8f3a2b",
  "last_id": "pres_7ff120"
}

The run object tracks status and progress:

Copy

{
  "id": "prot_seq_redes_8f3a2b",
  "status": "running", # pending | running | succeeded | failed | stopped
  "progress": {
    "total_proteins_to_generate": 40,
    "num_proteins_generated": 12,
    "latest_result_id": "pres_8f3a2b"
  },
  "error": None,
  "pipeline": "boltz-protein-redesign",
  "pipeline_version": "v2026-07-14",
  "livemode": True,
  "workspace_id": "ws_3a2b",
  "created_at": "2026-07-14T12:00:00Z",
  "started_at": "2026-07-14T12:00:03Z",
  "completed_at": None,
  "stopped_at": None,
  "data_deleted_at": None
  # "input" echoes the request body while data is retained
}

Download URLs expire. Check url_expires_at and download promptly. Once a URL expires, a new one can be generated until the data is deleted. By default data is retained for 7 days; see Data Retention.

Metric values and sequences shown in this guide are illustrative.