---
title: Get started | Boltz API Docs
description: Create an account, install a client, and run your first Boltz API job.
---

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](https://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](#tab-panel-0)
- [Scientist CLI](#tab-panel-1)
- [Platform Developer Python](#tab-panel-2)
- [Platform Developer Typescript](#tab-panel-3)
- [Agent CLI](#tab-panel-4)

Terminal window

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

Terminal window

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

Terminal window

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

Terminal window

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

Terminal window

```
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](#tab-panel-5)
- [Scientist CLI](#tab-panel-6)
- [Platform Developer Python](#tab-panel-7)
- [Platform Developer Typescript](#tab-panel-8)
- [Agent CLI](#tab-panel-9)

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

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:

Terminal window

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

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

```
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}`);
  }
}
```

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:

Terminal window

```
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](/docs/guides/predictions/index.md) — Submit a molecular complex and get predicted structures back.
- [Design small molecules](/docs/guides/small-molecule-design/index.md) — Generate novel small molecules against a protein target.
- [Screen small molecule libraries](/docs/guides/small-molecule-library-screen/index.md) — Score your own small molecules against a protein target.
- [Design proteins](/docs/guides/protein-design/index.md) — Generate novel protein binders against a target.
- [Screen protein libraries](/docs/guides/protein-library-screen/index.md) — Score your own protein sequences against a target.
- [Use an agent](/docs/guides/agent-integrations/index.md) — 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](/docs/guides/agent-integrations/index.md) for setup and prompt templates.