Start a protein library screen

$ boltz-api protein:library-screen start

POST/compute/v1/protein/library-screen

Screen a set of protein candidates against a target

ParametersExpand Collapse

--protein: array of object { entities, id }

List of protein entries to screen.

--target: object { chain_selection, structure, type } or object { entities, type, bonds, 3 more }

Target specification (structure template or template-free)

--idempotency-key: optional string

Client-provided key to prevent duplicate submissions on retries

maxLength255

--workspace-id: optional string

Target workspace ID (admin keys only; ignored for workspace keys)

ReturnsExpand Collapse

ProteinLibraryScreenStartResponse: object { id, completed_at, created_at, 12 more }

A protein library screening engine run

id: string

Unique ProteinLibraryScreen identifier

completed_at: string

formatdate-time

created_at: string

formatdate-time

data_deleted_at: string

When the input, output, and result data was permanently deleted. Null if data has not been deleted.

formatdate-time

engine: "boltz-protein-screen"

Engine used for protein library screen

engine_version: string

Engine version used for protein library screen

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 { proteins, target }

Pipeline input (null if data deleted)

proteins: object { url, url_expires_at }

url: string

URL to download the file

formaturi

url_expires_at: string

When the presigned URL expires

formatdate-time

target: object { chain_selection, structure, type } or object { entities, type, bonds, 3 more }

Target specification (structure template or template-free)

Accepts one of the following:

StructureTemplateTargetResponse: object { chain_selection, structure, type }

Target defined by an uploaded 3D structure (CIF or PDB file). Only chains included in chain_selection are used.

chain_selection: map[object { chain_type, crop_residues, epitope_residues, flexible_residues } or object { chain_type } ]

Chains selected from the uploaded structure, keyed by chain ID. Only chains listed here are included in the engine run — any chains omitted from this mapping are ignored. Each value defines which residues to keep, which are epitope residues, and which are flexible.

Accepts one of the following:

StructureTemplateTargetPolymerChainSpec: object { chain_type, crop_residues, epitope_residues, flexible_residues }

Per-chain specification for a polymer (protein/RNA/DNA) chain in a structure template target.

chain_type: "polymer"

crop_residues: array of number or "all"

0-indexed residue indices to retain from this chain, or 'all' to keep all residues. Residues not listed are excluded from the engine run.

Accepts one of the following:

union_member_0: array of number

0-indexed residue indices to keep

union_member_1: "all"

"all"

epitope_residues: optional array of number

0-indexed residue indices where binder contact is desired (the epitope). All indices must be present in crop_residues.

flexible_residues: optional array of number

0-indexed residue indices allowed to move during design (e.g. flexible loop regions). All indices must be present in crop_residues.

StructureTemplateTargetLigandChainSpec: object { chain_type }

Per-chain specification for a ligand chain in a structure template target. The full ligand is always included.

chain_type: "ligand"

structure: object { url, url_expires_at }

url: string

URL to download the file

formaturi

url_expires_at: string

When the presigned URL expires

formatdate-time

type: "structure_template"

NoTemplateTargetResponse: object { entities, type, bonds, 3 more }

Target defined by sequences only, without a 3D structure template

entities: array of object { chain_ids, type, value, 2 more } or object { chain_ids, type, value, 2 more } or object { chain_ids, type, value, 2 more } or 2 more

Entities (proteins, RNA, DNA, ligands) defining the target complex.

Accepts one of the following:

ProteinEntityResponse: object { chain_ids, type, value, 2 more }

chain_ids: array of string

Chain IDs for this entity

type: "protein"

value: string

Amino acid sequence (one-letter codes)

cyclic: optional boolean

Whether the sequence is cyclic

modifications: optional array of object { residue_index, type, value } or object { residue_index, type, value }

Post-translational modifications. Optional; defaults to an empty list when omitted.

Accepts one of the following:

CCDModificationResponse: object { residue_index, type, value }

residue_index: number

0-based index of the residue to modify

minimum0

type: "ccd"

value: string

CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

SmilesModificationResponse: object { residue_index, type, value }

residue_index: number

0-based index of the residue to modify

minimum0

type: "smiles"

value: string

SMILES string for the modification

RNAEntityResponse: object { chain_ids, type, value, 2 more }

chain_ids: array of string

Chain IDs for this entity

type: "rna"

value: string

RNA nucleotide sequence (A, C, G, U, N)

cyclic: optional boolean

Whether the sequence is cyclic

modifications: optional array of object { residue_index, type, value } or object { residue_index, type, value }

Chemical modifications. Optional; defaults to an empty list when omitted.

Accepts one of the following:

CCDModificationResponse: object { residue_index, type, value }

residue_index: number

0-based index of the residue to modify

minimum0

type: "ccd"

value: string

CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

SmilesModificationResponse: object { residue_index, type, value }

residue_index: number

0-based index of the residue to modify

minimum0

type: "smiles"

value: string

SMILES string for the modification

DNAEntityResponse: object { chain_ids, type, value, 2 more }

chain_ids: array of string

Chain IDs for this entity

type: "dna"

value: string

DNA nucleotide sequence (A, C, G, T, N)

cyclic: optional boolean

Whether the sequence is cyclic

modifications: optional array of object { residue_index, type, value } or object { residue_index, type, value }

Chemical modifications. Optional; defaults to an empty list when omitted.

Accepts one of the following:

CCDModificationResponse: object { residue_index, type, value }

residue_index: number

0-based index of the residue to modify

minimum0

type: "ccd"

value: string

CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for phosphoserine)

SmilesModificationResponse: object { residue_index, type, value }

residue_index: number

0-based index of the residue to modify

minimum0

type: "smiles"

value: string

SMILES string for the modification

LigandCCDEntityResponse: object { chain_ids, type, value }

chain_ids: array of string

Chain IDs for this ligand

type: "ligand_ccd"

value: string

CCD code (e.g., ATP, ADP)

LigandSmilesEntityResponse: object { chain_ids, type, value }

chain_ids: array of string

Chain IDs for this ligand

type: "ligand_smiles"

value: string

SMILES string representing the ligand

type: "no_template"

bonds: optional array of object { atom1, atom2 }

Covalent bond constraints between atoms in the target complex. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

atom1: object { atom_name, chain_id, type } or object { atom_name, chain_id, residue_index, type }

Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

Accepts one of the following:

LigandAtomResponse: object { atom_name, chain_id, type }

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"

PolymerAtomResponse: object { atom_name, chain_id, residue_index, type }

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

minimum0

type: "polymer_atom"

atom2: object { atom_name, chain_id, type } or object { atom_name, chain_id, residue_index, type }

Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

Accepts one of the following:

LigandAtomResponse: object { atom_name, chain_id, type }

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"

PolymerAtomResponse: object { atom_name, chain_id, residue_index, type }

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

minimum0

type: "polymer_atom"

constraints: optional array of object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more } or object { max_distance_angstrom, token1, token2, 2 more }

Structural constraints (pocket and contact). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

Accepts one of the following:

PocketConstraintResponse: object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }

Constrains the binder to interact with specific pocket residues on the target.

binder_chain_id: string

Chain ID of the binder molecule

contact_residues: map[array of number]

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"

force: optional boolean

Whether to force the constraint

ContactConstraintResponse: object { max_distance_angstrom, token1, token2, 2 more }

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: object { chain_id, residue_index, type } or object { atom_name, chain_id, type }

Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

Accepts one of the following:

PolymerContactTokenResponse: object { chain_id, residue_index, type }

chain_id: string

Chain ID

residue_index: number

0-based residue index

minimum0

type: "polymer_contact"

LigandContactTokenResponse: object { atom_name, chain_id, type }

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"

token2: object { chain_id, residue_index, type } or object { atom_name, chain_id, type }

Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

Accepts one of the following:

PolymerContactTokenResponse: object { chain_id, residue_index, type }

chain_id: string

Chain ID

residue_index: number

0-based residue index

minimum0

type: "polymer_contact"

LigandContactTokenResponse: object { atom_name, chain_id, type }

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"

type: "contact"

force: optional boolean

Whether to force the constraint

epitope_ligand_chains: optional array of string

Chain IDs of ligand entities that are part of the binding epitope. Ligands are marked as epitope in full (no residue-level selection).

epitope_residues: optional map[array of number]

Polymer chain residues where binder contact is desired (the epitope). Each key is a chain ID of a polymer entity, each value is an array of 0-indexed residue indices.

livemode: boolean

Whether this resource was created with a live API key.

progress: object { num_proteins_failed, num_proteins_screened, total_proteins_to_screen, latest_result_id }

num_proteins_failed: number

Number of accepted proteins that reached terminal failure during screening.

minimum0

num_proteins_screened: number

Number of accepted proteins that produced usable screening results.

minimum0

total_proteins_to_screen: number

Total number of proteins accepted into the screening run.

minimum1

latest_result_id: optional string

ID of the latest result

started_at: string

formatdate-time

status: "pending" or "running" or "succeeded" or 2 more

Accepts one of the following:

"pending"

"running"

"succeeded"

"failed"

"stopped"

stopped_at: string

formatdate-time

workspace_id: string

Workspace ID

idempotency_key: optional string

Client-provided idempotency key

Start a protein library screen

boltz-api protein:library-screen start \
  --protein '{entities: [{chain_ids: [string], type: protein, value: value, cyclic: true, modifications: [{residue_index: 0, type: ccd, value: value}]}], id: id}' \
  --target '{chain_selection: {A: {chain_type: polymer, crop_residues: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12], epitope_residues: [10, 11, 12], flexible_residues: [5, 6, 7]}}, structure: {type: url, url: https://example.com}, type: structure_template}'

{
  "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-screen",
  "engine_version": "engine_version",
  "error": {
    "code": "code",
    "message": "message",
    "details": {}
  },
  "input": {
    "proteins": {
      "url": "https://example.com",
      "url_expires_at": "2019-12-27T18:11:19.117Z"
    },
    "target": {
      "chain_selection": {
        "A": {
          "chain_type": "polymer",
          "crop_residues": [
            0,
            1,
            2,
            3,
            4,
            5,
            6,
            7,
            8,
            9,
            10,
            11,
            12
          ],
          "epitope_residues": [
            10,
            11,
            12
          ],
          "flexible_residues": [
            5,
            6,
            7
          ]
        }
      },
      "structure": {
        "url": "https://example.com",
        "url_expires_at": "2019-12-27T18:11:19.117Z"
      },
      "type": "structure_template"
    }
  },
  "livemode": true,
  "progress": {
    "num_proteins_failed": 0,
    "num_proteins_screened": 0,
    "total_proteins_to_screen": 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-screen",
  "engine_version": "engine_version",
  "error": {
    "code": "code",
    "message": "message",
    "details": {}
  },
  "input": {
    "proteins": {
      "url": "https://example.com",
      "url_expires_at": "2019-12-27T18:11:19.117Z"
    },
    "target": {
      "chain_selection": {
        "A": {
          "chain_type": "polymer",
          "crop_residues": [
            0,
            1,
            2,
            3,
            4,
            5,
            6,
            7,
            8,
            9,
            10,
            11,
            12
          ],
          "epitope_residues": [
            10,
            11,
            12
          ],
          "flexible_residues": [
            5,
            6,
            7
          ]
        }
      },
      "structure": {
        "url": "https://example.com",
        "url_expires_at": "2019-12-27T18:11:19.117Z"
      },
      "type": "structure_template"
    }
  },
  "livemode": true,
  "progress": {
    "num_proteins_failed": 0,
    "num_proteins_screened": 0,
    "total_proteins_to_screen": 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"
}