Start a protein sequence redesign run

$ boltz-api protein:sequence-redesign start

POST/compute/v1/protein/sequence-redesign

Create a protein sequence redesign run from selected residues in a fixed input structure

ParametersExpand Collapse

--entity: array of object { chain_id, role, type } or object { chain_id, role, type, design_motifs }

Every chain in the input CIF, assigned exactly once as target or binder.

--num-proteins: number

Number of unique filter-passing redesigned proteins to generate.

--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.

--type: "binder"

--global-design-filter: optional array of object { amino_acids, type } or object { max_fraction, type } or object { motifs, type }

Filters applied to every redesigned region. When omitted, cysteine is excluded. Pass [] to disable global filters.

--idempotency-key: optional string

--workspace-id: optional string

Workspace to run this redesign in.

ReturnsExpand Collapse

ProteinSequenceRedesignStartResponse: object { id, completed_at, created_at, 14 more }

A fixed-structure protein sequence redesign run.

id: string

Unique ProteinSequenceRedesignRun 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.

Deprecatedengine: "boltz-protein-redesign"

Use pipeline instead.

Deprecated. Use pipeline instead.

Deprecatedengine_version: "v2026-07-14"

Use pipeline_version instead.

Deprecated. Use pipeline_version instead.

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 { entities, num_proteins, structure, 4 more } or object { entities, num_proteins, structure, 4 more }

Pipeline input (null if data deleted)

BinderProteinSequenceRedesignRunInputResponse: object { entities, num_proteins, structure, 4 more }

entities: array of object { chain_id, role, type } or object { chain_id, role, type, design_motifs }

Every chain in the input CIF, assigned exactly once as target or binder.

BinderSequenceRedesignTargetEntityResponse: object { chain_id, role, type }

A fixed target chain from the input CIF.

chain_id: string

role: "target"

type: "from_template"

BinderSequenceRedesignBinderEntityResponse: object { chain_id, role, type, design_motifs }

chain_id: string

role: "binder"

type: "from_template"

design_motifs: optional array of object { filters, residues, type }

Residues to redesign. Omit this field to keep the binder chain fixed.

filters: array of object { amino_acids, type } or object { max_fraction, type } or object { motifs, type }

Filters applied to this motif in addition to global_design_filters.

ExcludedAminoAcidsDesignFilterResponse: object { amino_acids, type }

amino_acids: array of string

Single-letter amino-acid codes that must not occur in the filtered designed region.

type: "excluded_amino_acids"

MaxHydrophobicFractionDesignFilterResponse: object { max_fraction, type }

max_fraction: number

type: "max_hydrophobic_fraction"

ExcludedSequenceMotifsDesignFilterResponse: object { motifs, type }

motifs: array of string

Sequence motifs that must not occur. X matches any single residue.

type: "excluded_sequence_motifs"

residues: array of number

0-indexed residues to redesign on this chain.

type: "residues"

num_proteins: number

Number of unique filter-passing redesigned proteins to generate.

structure: object { url, url_expires_at }

url: string

URL to download the file

url_expires_at: string

When the presigned URL expires

type: "binder"

global_design_filters: optional array of object { amino_acids, type } or object { max_fraction, type } or object { motifs, type }

Filters applied to every redesigned region. When omitted, cysteine is excluded. Pass [] to disable global filters.

ExcludedAminoAcidsDesignFilterResponse: object { amino_acids, type }

amino_acids: array of string

Single-letter amino-acid codes that must not occur in the filtered designed region.

type: "excluded_amino_acids"

MaxHydrophobicFractionDesignFilterResponse: object { max_fraction, type }

max_fraction: number

type: "max_hydrophobic_fraction"

ExcludedSequenceMotifsDesignFilterResponse: object { motifs, type }

motifs: array of string

Sequence motifs that must not occur. X matches any single residue.

type: "excluded_sequence_motifs"

idempotency_key: optional string

workspace_id: optional string

Workspace to run this redesign in.

GenericProteinSequenceRedesignRunInputResponse: object { entities, num_proteins, structure, 4 more }

entities: array of object { chain_id, type, design_motifs }

Every chain in the input CIF, assigned exactly once.

chain_id: string

type: "from_template"

design_motifs: optional array of object { filters, residues, type }

Residues to redesign. Omit this field to keep the chain fixed.

filters: array of object { amino_acids, type } or object { max_fraction, type } or object { motifs, type }

Filters applied to this motif in addition to global_design_filters.

ExcludedAminoAcidsDesignFilterResponse: object { amino_acids, type }

amino_acids: array of string

Single-letter amino-acid codes that must not occur in the filtered designed region.

type: "excluded_amino_acids"

MaxHydrophobicFractionDesignFilterResponse: object { max_fraction, type }

max_fraction: number

type: "max_hydrophobic_fraction"

ExcludedSequenceMotifsDesignFilterResponse: object { motifs, type }

motifs: array of string

Sequence motifs that must not occur. X matches any single residue.

type: "excluded_sequence_motifs"

residues: array of number

0-indexed residues to redesign on this chain.

type: "residues"

num_proteins: number

Number of unique filter-passing redesigned proteins to generate.

structure: object { url, url_expires_at }

url: string

URL to download the file

url_expires_at: string

When the presigned URL expires

type: "generic"

global_design_filters: optional array of object { amino_acids, type } or object { max_fraction, type } or object { motifs, type }

Filters applied to every redesigned region. When omitted, cysteine is excluded. Pass [] to disable global filters.

ExcludedAminoAcidsDesignFilterResponse: object { amino_acids, type }

amino_acids: array of string

Single-letter amino-acid codes that must not occur in the filtered designed region.

type: "excluded_amino_acids"

MaxHydrophobicFractionDesignFilterResponse: object { max_fraction, type }

max_fraction: number

type: "max_hydrophobic_fraction"

ExcludedSequenceMotifsDesignFilterResponse: object { motifs, type }

motifs: array of string

Sequence motifs that must not occur. X matches any single residue.

type: "excluded_sequence_motifs"

idempotency_key: optional string

workspace_id: optional string

Workspace to run this redesign in.

livemode: boolean

Whether this resource was created with a live API key.

pipeline: "boltz-protein-redesign"

pipeline_version: "v2026-07-14"

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

Start a protein sequence redesign run

boltz-api protein:sequence-redesign start \
  --api-key 'My API Key' \
  --entity '{chain_id: x, role: target, type: from_template}' \
  --entity '{chain_id: x, role: target, type: from_template}' \
  --num-proteins 1 \
  --structure '{type: url, url: https://example.com}' \
  --type binder

{
  "id": "id",
  "completed_at": "2019-12-27T18:11:19.117Z",
  "created_at": "2019-12-27T18:11:19.117Z",
  "data_deleted_at": "2019-12-27T18:11:19.117Z",
  "engine": "boltz-protein-redesign",
  "engine_version": "v2026-07-14",
  "error": {
    "code": "code",
    "message": "message",
    "details": {}
  },
  "input": {
    "entities": [
      {
        "chain_id": "x",
        "role": "target",
        "type": "from_template"
      },
      {
        "chain_id": "x",
        "role": "target",
        "type": "from_template"
      }
    ],
    "num_proteins": 1,
    "structure": {
      "url": "https://example.com",
      "url_expires_at": "2019-12-27T18:11:19.117Z"
    },
    "type": "binder",
    "global_design_filters": [
      {
        "amino_acids": [
          "x"
        ],
        "type": "excluded_amino_acids"
      }
    ],
    "idempotency_key": "idempotency_key",
    "workspace_id": "workspace_id"
  },
  "livemode": true,
  "pipeline": "boltz-protein-redesign",
  "pipeline_version": "v2026-07-14",
  "progress": {
    "num_proteins_generated": 0,
    "total_proteins_to_generate": 1,
    "latest_result_id": "latest_result_id"
  },
  "started_at": "2019-12-27T18:11:19.117Z",
  "status": "pending",
  "stopped_at": "2019-12-27T18:11:19.117Z",
  "workspace_id": "workspace_id",
  "idempotency_key": "idempotency_key"
}

Returns Examples

{
  "id": "id",
  "completed_at": "2019-12-27T18:11:19.117Z",
  "created_at": "2019-12-27T18:11:19.117Z",
  "data_deleted_at": "2019-12-27T18:11:19.117Z",
  "engine": "boltz-protein-redesign",
  "engine_version": "v2026-07-14",
  "error": {
    "code": "code",
    "message": "message",
    "details": {}
  },
  "input": {
    "entities": [
      {
        "chain_id": "x",
        "role": "target",
        "type": "from_template"
      },
      {
        "chain_id": "x",
        "role": "target",
        "type": "from_template"
      }
    ],
    "num_proteins": 1,
    "structure": {
      "url": "https://example.com",
      "url_expires_at": "2019-12-27T18:11:19.117Z"
    },
    "type": "binder",
    "global_design_filters": [
      {
        "amino_acids": [
          "x"
        ],
        "type": "excluded_amino_acids"
      }
    ],
    "idempotency_key": "idempotency_key",
    "workspace_id": "workspace_id"
  },
  "livemode": true,
  "pipeline": "boltz-protein-redesign",
  "pipeline_version": "v2026-07-14",
  "progress": {
    "num_proteins_generated": 0,
    "total_proteins_to_generate": 1,
    "latest_result_id": "latest_result_id"
  },
  "started_at": "2019-12-27T18:11:19.117Z",
  "status": "pending",
  "stopped_at": "2019-12-27T18:11:19.117Z",
  "workspace_id": "workspace_id",
  "idempotency_key": "idempotency_key"
}