API Reference

Small Molecule

Library Screen

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Stop a running small molecule library screen

$ boltz-api small-molecule:library-screen stop

POST/compute/v1/small-molecule/library-screen/{id}/stop

Stop an in-progress library screen early

ParametersExpand Collapse

--id: string

Library screen ID

ReturnsExpand Collapse

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

A small molecule library screening engine run

id: string

Unique SmScreen 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-sm-screen"

Engine used for small molecule library screen

engine_version: string

Engine version used for small molecule 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 { molecules, target, molecule_filters }

Pipeline input (null if data deleted)

molecules: 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 { entities, bonds, constraints, 2 more }

Target protein with binding pocket for small molecule design or screening

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

Protein entities defining the target structure. Each entity represents a protein chain.

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

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

pocket_residues: optional 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 binding pocket on that chain. When provided, these residues guide pocket extraction and add a derived pocket constraint during affinity predictions. That derived constraint remains separate from any explicit pocket constraints in target.constraints. When omitted, the model auto-detects the pocket.

reference_ligands: optional array of string

Reference ligands as SMILES strings that help the model identify the binding pocket. When omitted, a set of drug-like default ligands is used for pocket detection.

molecule_filters: optional object { boltz_smarts_catalog_filter_level, custom_filters }

Molecule filtering configuration. Controls both Boltz built-in SMARTS filtering and custom filters.

boltz_smarts_catalog_filter_level: optional "recommended" or "extra" or "aggressive" or "disabled"

Controls the stringency of Boltz's built-in SMARTS structural alert filtering, which removes molecules matching known problematic substructures. 'recommended' (default): applies a curated set of alerts balancing safety and hit rate. 'extra': adds additional alerts beyond the recommended set for stricter filtering. 'aggressive': applies the most comprehensive alert set — may reject viable molecules. 'disabled': turns off Boltz SMARTS filtering entirely; only custom_filters will be applied.

Accepts one of the following:

"recommended"

"extra"

"aggressive"

"disabled"

custom_filters: optional array of object { max_hba, max_hbd, max_logp, 3 more } or object { type, fraction_csp3, mol_logp, 8 more } or object { patterns, type } or 2 more

Custom filters to apply. Molecules must pass all filters (AND logic).

Accepts one of the following:

LipinskiFilterResponse: object { max_hba, max_hbd, max_logp, 3 more }

Lipinski's Rule of Five filter. Rejects molecules that violate drug-likeness criteria based on molecular weight, LogP, hydrogen bond donors, and hydrogen bond acceptors.

max_hba: number

Maximum number of hydrogen bond acceptors. Lipinski threshold: 10

max_hbd: number

Maximum number of hydrogen bond donors. Lipinski threshold: 5

max_logp: number

Maximum LogP. Lipinski threshold: 5

max_mw: number

Maximum molecular weight (Da). Lipinski threshold: 500

type: "lipinski_filter"

allow_single_violation: optional boolean

If true, one rule violation is allowed (classic Rule of Five). Defaults to false (all rules must pass).

RdkitDescriptorFilterResponse: object { type, fraction_csp3, mol_logp, 8 more }

Filter molecules by RDKit molecular descriptors. Each descriptor is constrained to a min/max range. Only descriptors you provide are checked — omitted descriptors are unconstrained.

type: "rdkit_descriptor_filter"

fraction_csp3: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

mol_logp: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

mol_wt: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

num_aromatic_rings: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

num_h_acceptors: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

num_h_donors: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

num_heteroatoms: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

num_rings: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

num_rotatable_bonds: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

tpsa: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

SmartsCustomFilterResponse: object { patterns, type }

Filter molecules by custom SMARTS patterns. Molecules matching any pattern are rejected.

patterns: array of string

SMARTS patterns. Molecules matching any pattern are rejected.

type: "smarts_custom_filter"

SmartsCatalogFilterResponse: object { catalog, type }

Filter molecules using a predefined SMARTS catalog of structural alerts.

catalog: "PAINS" or "PAINS_A" or "PAINS_B" or 11 more

Predefined SMARTS catalog to apply. PAINS, BRENK, ChEMBL, and NIH catalogs reject known problematic substructures.

Accepts one of the following:

"PAINS"

"PAINS_A"

"PAINS_B"

"PAINS_C"

"BRENK"

"CHEMBL"

"CHEMBL_BMS"

"CHEMBL_Dundee"

"CHEMBL_Glaxo"

"CHEMBL_Inpharmatica"

"CHEMBL_LINT"

"CHEMBL_MLSMR"

"CHEMBL_SureChEMBL"

"NIH"

type: "smarts_catalog_filter"

SmilesRegexFilterResponse: object { patterns, type }

Filter molecules by regex patterns on their SMILES representation.

patterns: array of string

Regex patterns applied to SMILES strings. Molecules matching any pattern are rejected.

type: "smiles_regex_filter"

livemode: boolean

Whether this resource was created with a live API key.

progress: object { num_molecules_failed, num_molecules_screened, total_molecules_to_screen, 2 more }

num_molecules_failed: number

Number of accepted molecules that reached terminal failure during screening.

minimum0

num_molecules_screened: number

Number of accepted molecules that produced usable screening results.

minimum0

total_molecules_to_screen: number

Total number of molecules accepted into screening after server-side validation and filtering.

minimum0

latest_result_id: optional string

ID of the most recently screened result

rejection_summary: optional object { filtered_count, invalid_count }

filtered_count: number

Number of submitted molecules removed by server-side filtering rules.

minimum0

invalid_count: number

Number of submitted molecules rejected as invalid input.

minimum0

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

Stop a running small molecule library screen

CLI Tool

HTTP

TypeScript

Python

Go

CLI Tool

boltz-api small-molecule:library-screen stop \
  --id id

200 example

{
  "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-sm-screen",
  "engine_version": "engine_version",
  "error": {
    "code": "code",
    "message": "message",
    "details": {}
  },
  "input": {
    "molecules": {
      "url": "https://example.com",
      "url_expires_at": "2019-12-27T18:11:19.117Z"
    },
    "target": {
      "entities": [
        {
          "chain_ids": [
            "string"
          ],
          "type": "protein",
          "value": "value",
          "cyclic": true,
          "modifications": [
            {
              "residue_index": 0,
              "type": "ccd",
              "value": "value"
            }
          ]
        }
      ],
      "bonds": [
        {
          "atom1": {
            "atom_name": "atom_name",
            "chain_id": "chain_id",
            "type": "ligand_atom"
          },
          "atom2": {
            "atom_name": "atom_name",
            "chain_id": "chain_id",
            "type": "ligand_atom"
          }
        }
      ],
      "constraints": [
        {
          "binder_chain_id": "binder_chain_id",
          "contact_residues": {
            "A": [
              42,
              43,
              44,
              67,
              68,
              69
            ]
          },
          "max_distance_angstrom": 0,
          "type": "pocket",
          "force": true
        }
      ],
      "pocket_residues": {
        "A": [
          42,
          43,
          44,
          67,
          68,
          69
        ]
      },
      "reference_ligands": [
        "string"
      ]
    },
    "molecule_filters": {
      "boltz_smarts_catalog_filter_level": "recommended",
      "custom_filters": [
        {
          "max_hba": 0,
          "max_hbd": 0,
          "max_logp": 0,
          "max_mw": 0,
          "type": "lipinski_filter",
          "allow_single_violation": true
        }
      ]
    }
  },
  "livemode": true,
  "progress": {
    "num_molecules_failed": 0,
    "num_molecules_screened": 0,
    "total_molecules_to_screen": 0,
    "latest_result_id": "latest_result_id",
    "rejection_summary": {
      "filtered_count": 0,
      "invalid_count": 0
    }
  },
  "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

200 example

{
  "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-sm-screen",
  "engine_version": "engine_version",
  "error": {
    "code": "code",
    "message": "message",
    "details": {}
  },
  "input": {
    "molecules": {
      "url": "https://example.com",
      "url_expires_at": "2019-12-27T18:11:19.117Z"
    },
    "target": {
      "entities": [
        {
          "chain_ids": [
            "string"
          ],
          "type": "protein",
          "value": "value",
          "cyclic": true,
          "modifications": [
            {
              "residue_index": 0,
              "type": "ccd",
              "value": "value"
            }
          ]
        }
      ],
      "bonds": [
        {
          "atom1": {
            "atom_name": "atom_name",
            "chain_id": "chain_id",
            "type": "ligand_atom"
          },
          "atom2": {
            "atom_name": "atom_name",
            "chain_id": "chain_id",
            "type": "ligand_atom"
          }
        }
      ],
      "constraints": [
        {
          "binder_chain_id": "binder_chain_id",
          "contact_residues": {
            "A": [
              42,
              43,
              44,
              67,
              68,
              69
            ]
          },
          "max_distance_angstrom": 0,
          "type": "pocket",
          "force": true
        }
      ],
      "pocket_residues": {
        "A": [
          42,
          43,
          44,
          67,
          68,
          69
        ]
      },
      "reference_ligands": [
        "string"
      ]
    },
    "molecule_filters": {
      "boltz_smarts_catalog_filter_level": "recommended",
      "custom_filters": [
        {
          "max_hba": 0,
          "max_hbd": 0,
          "max_logp": 0,
          "max_mw": 0,
          "type": "lipinski_filter",
          "allow_single_violation": true
        }
      ]
    }
  },
  "livemode": true,
  "progress": {
    "num_molecules_failed": 0,
    "num_molecules_screened": 0,
    "total_molecules_to_screen": 0,
    "latest_result_id": "latest_result_id",
    "rejection_summary": {
      "filtered_count": 0,
      "invalid_count": 0
    }
  },
  "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"
}