<!-- Source: https://docs.biosimulant.com/developer-api/quickstart -->

# 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](https://studio.biosimulant.com/developer), 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`

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

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

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

```text
demi/microbiology-hello-world-growth@1.0.0
```

**Tip:**

  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

```python
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](https://studio.biosimulant.com/developer) 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](/developer-api/errors).

## Next steps

- [Run lifecycle](/developer-api/runs)
- [Python examples](/developer-api/examples)
- [REST reference](/developer-api/rest-reference)
- [Webhooks](/developer-api/webhooks)