Developer API quickstart

Create a scoped API key and run one pinned public lab as a durable managed job.

Before you start

Time: about 10 minutes.
Requirements: Python 3.10+, a Biosimulant account with available compute, and permission to create a Developer API key.
Outcome: a completed managed run with outputs and the exact resolved package reference.

1. Create an API key

Sign in to the developer console, select Create key, and copy the bsk_live_... value when it appears. The secret is shown once; the service stores only its hash and display prefix.

A new key carries every developer scope. They are the same scopes the MCP server uses:

hub:read: search the Hub and list the Labs you own
biology:read: search and fetch external biological evidence
workspaces:read, workspaces:write: read, create and change private labs, and upload files
runs:read, runs:write: list, start and cancel runs and experiments
passports:read: read Evidence Passports
packages:publish: publish releases and change Lab visibility or details

Keys made before these names existed keep working: capabilities:read and packages:read count as hub:read, and packages:write counts as packages:publish.

packages:publish (or packages:write) lets the key publish to the Hub under your namespace. If the key is only meant to submit runs, narrow its scopes when you create it.

A key acts only for the account that created it. Every list returns only that account’s records, and an ID belonging to anyone else is answered exactly like an ID that does not exist.

The same key is what biosimulant auth login stores as its registry token, so one key covers the Developer API and private pulls or publishes from the CLI.

export BIOSIMULANT_API_KEY="bsk_live_..."

Never commit a key or place it in browser-side code. Revoke a key from the developer console if it is exposed.

Team keys

If you belong to a team, choose the team next to Create key to make a key for it. A team key:

lists and reads only the team’s records, never your personal ones;
creates workspaces and runs that belong to the team;
publishes under the team’s namespace;
does no more than your role allows. A Viewer’s key can read but not create.

It stops working if you leave the team, and team Admins can revoke it from the team’s Integrations tab. GET /v1/account reports the account a key works in.

2. Install the Python package

python -m pip install "biosimulant>=0.0.19"

This is the primary biosimulant distribution; there is no separate cloud package.

3. Run a pinned lab

from biosimulant import Client
 
with Client() as client:
    result = client.run(
        "demi/microbiology-hello-world-growth@1.0.0",
        inputs={
            "initial_cells": 10,
            "available_food": 80,
        },
        timeout=300,
    )
 
print(result.outputs)
print(result.provenance["resolved_ref"])

Client() reads BIOSIMULANT_API_KEY. Set BIOSIMULANT_API_BASE_URL only for a staging or local API environment.

Verify the result

The command should print an outputs dictionary followed by:

demi/microbiology-hello-world-growth@1.0.0

A reference without @version resolves the latest accessible version when the run is created. Pin namespace/name@version in production and reproducible workflows.

4. Return immediately instead

with Client() as client:
    run = client.runs.create(
        ref="demi/microbiology-hello-world-growth@1.0.0",
        inputs={"initial_cells": 10},
        metadata={"sample_id": "plate-17"},
    )
    print(run.id, run.status)

Persist the run ID. You can retrieve the run later with client.runs.retrieve(run_id).

5. Find what you already have

The same key lists everything your account owns, whether you started it here, in Studio, or through an assistant connected over MCP:

curl -H "Authorization: Bearer $BIOSIMULANT_API_KEY" https://api.biosimulant.com/v1/runs
curl -H "Authorization: Bearer $BIOSIMULANT_API_KEY" https://api.biosimulant.com/v1/labs
curl -H "Authorization: Bearer $BIOSIMULANT_API_KEY" https://api.biosimulant.com/v1/experiments

Each list is newest first. Pass next_cursor back as cursor for the next page. See Managed labs from code to change a lab and run it with an approved plan.

Troubleshooting

Authentication error: confirm the key starts with bsk_live_, has not been revoked, and is exported in the same shell running Python.
Insufficient scope: create or update a key with hub:read, runs:read, and runs:write.
gateway_not_enabled: routes that start managed compute, publish, change a workspace or call external sources follow the Agent Gateway switch for your account. Reads work without it.
Not enough compute: open the developer console to review your monthly compute, and add compute on the Billing page (Settings → Billing).
Timeout: the caller timeout does not cancel the managed run. Persist the run ID and retrieve it later.
Validation or rate-limit error: see Errors, limits and compute.

Next steps

Overview Runs and results