Get started

The Boltz API lets you run structure prediction, molecular design, and library screening from code.

Create an account

Create an account at api.boltz.bio. You can create API keys from the Boltz API dashboard after signing in.

Start running jobs

Install a client and authenticate it:

Scientist Python

pip install boltz-api
export BOLTZ_API_KEY="your-api-key"

Scientist CLI

curl -fsSL https://install.boltz.bio/boltz-api/install.sh | sh
boltz-api auth login

Platform Developer Python

pip install boltz-api
export BOLTZ_API_KEY="your-api-key"

Platform Developer Typescript

npm install boltz-api
export BOLTZ_API_KEY="your-api-key"

Agent CLI

curl -fsSL https://install.boltz.bio/boltz-api/install.sh | sh
boltz-api auth login --device-code
export BOLTZ_COMPUTE_OUTPUT_DIR="$HOME/boltz-experiments"

Predict structure and binding

This example evaluates a protein-ligand complex with Boltz 2.1.

Scientist Python

import os
from boltz_api import Boltz

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

run_dir = client.experiments.run_structure_and_binding(
    entities=[
        {"type": "protein", "value": "MKTIIALSYIFCLVFA", "chain_ids": ["A"]},
        {
            "type": "ligand_smiles",
            "value": "CC(=O)OC1=CC=CC=C1C(=O)O",
            "chain_ids": ["B"],
        },
    ],
    model="boltz-2.1",
    name="aspirin-check",
)

print(run_dir)

Scientist CLI

Save your inputs to prediction-input.yaml:

entities:
  - type: protein
    value: MKTIIALSYIFCLVFA
    chain_ids: ["A"]
  - type: ligand_smiles
    value: CC(=O)OC1=CC=CC=C1C(=O)O
    chain_ids: ["B"]

Then submit and download:

PREDICTION_ID=$(
  boltz-api --format raw predictions:structure-and-binding start \
    --model boltz-2.1 \
    --input @yaml://./prediction-input.yaml |
    jq -r '.id'
)

boltz-api download-results --id "$PREDICTION_ID" --name aspirin-check

Platform Developer Python

import time
import os
from boltz_api import Boltz

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

# Start a structure prediction
prediction = client.predictions.structure_and_binding.start(
    model="boltz-2.1",
    input={
        "entities": [
            {"type": "protein", "value": "MKTIIALSYIFCLVFA", "chain_ids": ["A"]},
            {
                "type": "ligand_smiles",
                "value": "CC(=O)OC1=CC=CC=C1C(=O)O",
                "chain_ids": ["B"],
            },
        ],
    },
)
print(f"Started prediction: {prediction.id}")

# Poll until complete
while prediction.status not in ("succeeded", "failed"):
    time.sleep(5)
    prediction = client.predictions.structure_and_binding.retrieve(prediction.id)
    print(f"Status: {prediction.status}")

# Download the structure
if prediction.status == "succeeded":
    for sample in prediction.output.all_sample_results:
        print(f"Structure confidence: {sample.metrics.structure_confidence}")
        print(f"Download: {sample.structure.url}")

Platform Developer Typescript

import Boltz from "boltz-api";

const apiKey = process.env["BOLTZ_API_KEY"];

const client = new Boltz({ apiKey });

// Start a structure prediction
let prediction = await client.predictions.structureAndBinding.start({
  model: "boltz-2.1",
  input: {
    entities: [
      { type: "protein", value: "MKTIIALSYIFCLVFA", chain_ids: ["A"] },
      {
        type: "ligand_smiles",
        value: "CC(=O)OC1=CC=CC=C1C(=O)O",
        chain_ids: ["B"],
      },
    ],
  },
});
console.log(`Started prediction: ${prediction.id}`);

// Poll until complete
while (prediction.status !== "succeeded" && prediction.status !== "failed") {
  await new Promise((r) => setTimeout(r, 5000));
  prediction = await client.predictions.structureAndBinding.retrieve(
    prediction.id,
  );
  console.log(`Status: ${prediction.status}`);
}

// Download the structure
if (prediction.status === "succeeded") {
  for (const sample of prediction.output.all_sample_results) {
    console.log(`Structure confidence: ${sample.metrics.structure_confidence}`);
    console.log(`Download: ${sample.structure.url}`);
  }
}

Agent CLI

Ask the agent to save the payload to prediction-input.yaml:

entities:
  - type: protein
    value: MKTIIALSYIFCLVFA
    chain_ids: ["A"]
  - type: ligand_smiles
    value: CC(=O)OC1=CC=CC=C1C(=O)O
    chain_ids: ["B"]

Then have it estimate cost, submit with an idempotency key, and download results:

boltz-api predictions:structure-and-binding estimate-cost \
  --model boltz-2.1 \
  --input @yaml://./prediction-input.yaml

boltz-api predictions:structure-and-binding start \
  --model boltz-2.1 \
  --idempotency-key "aspirin-check" \
  --input @yaml://./prediction-input.yaml \
  --raw-output --transform id

boltz-api download-results \
  --id "<prediction-id-from-start>" \
  --name "aspirin-check" \
  --root-dir "./boltz-experiments" \
  --poll-interval-seconds 10

Choose your next job

Choose the guide that matches the work you want to do:

• Predict structure and binding — Submit a molecular complex and get predicted structures back.
• Design small molecules — Generate novel small molecules against a protein target.
• Screen small molecule libraries — Score your own small molecules against a protein target.
• Design proteins — Generate novel protein binders against a target.
• Screen protein libraries — Score your own protein sequences against a target.
• Use an agent — Run Boltz from Claude Code, Codex, Cursor, or another coding agent.

Scientist workflows

The Scientist tab uses client.experiments. A run_*() call submits the job, waits for completion, downloads outputs, and returns a local run directory under ./boltz-experiments/.

Use start_*() and wait_and_download() when you want to submit now and collect results later.

Agent workflows

The Agent tab uses the same boltz-api CLI but favors permission-friendly commands: write an input file, estimate cost, submit with --idempotency-key, then download with the same run name and output root. See Agent integrations for setup and prompt templates.