> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heybee.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Run the full evaluation lifecycle from Python, sync or async.

```bash theme={null}
pip install heybee
```

Authenticate with an API key for servers and CI, or with browser login for local tools:

```bash theme={null}
export HEYBEE_API_KEY="hb_..."   # or run: heybee auth login
```

API keys are created under **Account settings → Security & API** on Pro and above, and are shown only once.

## Quickstart

```python theme={null}
from heybee import AsyncHeyBee, ExperimentSpec

async with AsyncHeyBee() as client:
    evaluation = await client.create_evaluation(
        ExperimentSpec(name='Response quality', type='text', requires_anchor=False)
    )
    await client.upload_samples(evaluation.id, samples)

    link = await client.create_collection_link(evaluation.id)
    print(f'Vote here: {link.voting_url}')

    state = await client.monitor_evaluation(evaluation.id)
    results = await client.export_results(evaluation.id)
```

The synchronous `HeyBee` client exposes the same operations through resource namespaces, for example `client.evaluations.create(spec)` and `client.voting_links.create(...)`.

## Good to know

* **Safe retries**: the client retries only reads and idempotent writes, so a flaky connection never duplicates an evaluation or a purchase. Pass `idempotency_key` to make any write safely retryable.
* **Errors**: every error is typed and carries the HTTP status, an error code, and a request ID you can hand to support.
* **Full API surface**: import `OpenAPIClient` (or `AnonymousOpenAPIClient` for public endpoints) for direct access to every operation in the API reference, generated from the same OpenAPI document.