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

# Developer API

The Biosimulant Developer API runs versioned Hub labs as durable managed jobs. It is available through the same MIT-licensed `biosimulant` Python distribution used for local simulation.

```python
from biosimulant import Client

client = Client()  # reads BIOSIMULANT_API_KEY
result = client.run(
    "demi/microbiology-hello-world-growth@1.0.0",
    inputs={"initial_cells": 10, "available_food": 80},
    timeout=300,
)
```

## Local versus managed execution

`BioWorld.run()` stays local, open source, and free. `Client` and `AsyncClient` are explicit managed-cloud interfaces. They submit to `https://api.biosimulant.com/v1`; no local call silently moves to hosted infrastructure. To resolve a pinned Hub Lab into a local world instead, use [`HubComposition`](/references/library/hub-composition-api).

The two modes share the same runtime, the same package refs, and the same results contract. What differs is where the work runs and what the platform manages for you:

| | Local: `BioWorld.run()` | Managed: `Client` / `AsyncClient` |
|---|---|---|
| Where it runs | Your machine or CI | `api.biosimulant.com/v1` |
| Entry point | `world.run(duration=…)`, `run_package(…)`, CLI | `client.run(ref, inputs=…)` |
| Install | `pip install biosimulant` | Same package, plus an API key |
| Licensing & cost | MIT, free | Prepaid [credits](/developer-api/billing) |
| Compute | Your local CPU/GPU | Managed CPU/GPU [profiles](/developer-api/billing) |
| Durability | Ends with your process | Durable server job, survives client timeouts |
| Provenance & artifacts | You persist them | Attached to every run automatically |
| Delivery | Synchronous return | Poll a run handle or receive [webhooks](/developer-api/webhooks) |
| Best for | Development, tests, offline work, CI | Long or GPU-heavy runs, shared results, automation |

The same hello-world lab, run each way:

  
### Local (CLI)

    ```bash
    # Runs on your machine. MIT, free, offline.
    # labs run pulls or reuses the ref, then runs it locally.
    biosimulant labs run demi/microbiology-hello-world-growth@1.0.0 \
      --parameters-file inputs.json \
      --results-file results.json
    ```
  
  
### Cloud (Python)

    ```python
    from biosimulant import Client

    # Submits a durable managed job. Same ref, same results contract.
    client = Client()  # reads BIOSIMULANT_API_KEY
    result = client.run(
        "demi/microbiology-hello-world-growth@1.0.0",
        inputs={"initial_cells": 10, "available_food": 80},
        timeout=300,
    )
    print(result.outputs)
    ```
  

Cloud runs are always durable and asynchronous on the server:

- `client.runs.create(...)` returns a run handle immediately.
- `client.run(...)` is a convenience that blocks the calling thread while polling.
- `await AsyncClient().run(...)` waits without blocking the event loop.
- A client-side timeout leaves the server run active and returns its handle on `RunTimeout`.

**Info:**

  The first release executes accessible, versioned Hub labs. Arbitrary `BioWorld` serialization and private local-lab upload through the SDK are not part of this release.

## Start here

1. [Create a scoped API key and complete the quickstart](/developer-api/quickstart).
2. Learn the [durable run lifecycle](/developer-api/runs).
3. Read the [reference and data contract](/developer-api/data-contract).
4. Choose from the [tested Python patterns](/developer-api/examples).
5. Use the [REST reference](/developer-api/rest-reference) for direct HTTP integration.
6. See the [supported Python API surface](/references/library/python-api) for the complete public import inventory.