---
title: Redesign protein sequences | Boltz API Docs
description: Redesign selected residues in a fixed single-CIF structure, with binder or generic chain assignments that cover the entire structure.
---

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`](/docs/guides/protein-design/index.md) 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](#tab-panel-27)
- [CLI](#tab-panel-28)
- [TypeScript](#tab-panel-29)

```
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": [],
}
],
},
],
)
```

Write your request body to `protein-sequence-redesign.json` (see [Input format](#input-format)), then:

Terminal window

```
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"
```

```
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](/docs/guides/data-retention/index.md).

Metric values and sequences shown in this guide are illustrative.

```
```