Developer APIQuickstart

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 credits, 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.

The default key scopes are:

  • capabilities:read
  • runs:read
  • runs:write
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.

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

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 capabilities:read, runs:read, and runs:write.
  • Insufficient credits: open the developer console and review usage and credit packs.
  • Timeout: the caller timeout does not cancel the managed run. Persist the run ID and retrieve it later.
  • Validation or rate-limit error: follow Errors, retries, and rate limits.

Next steps

OverviewRun lifecycle