# Python SDK preview

**This page previews the Python client hlix will publish.** It is generated from the same OpenAPI 3.1 contract as the TypeScript SDK, and the shapes below are the ones the published package will expose.
**Preview, not a registry release:** Nothing is published yet, and **no PyPI name is reserved**. Do not add a `hlix-sdk` dependency until [Current versions](/releases/availability/) shows a verified version — a package answering that name today is not hlix's.

## Prerequisites

- Python 3.10 or later
- An hlix API key and workspace ID

## Generate a client meanwhile

The [OpenAPI contract](/api/openapi/) is public and needs no authentication, so you can generate a working Python client now:

```bash
curl --fail --silent --show-error \
  https://server.hlix.ai/v1/api/openapi.json \
  --output hlix-openapi.json

npx @openapitools/openapi-generator-cli generate \
  -i hlix-openapi.json \
  -g python \
  -o ./hlix-client
```

Expected result: a package whose operations match the [API reference](/api/reference/) one for one. hlix pins OpenAPI Generator `7.22.0` for its own previews; pinning yours keeps regeneration reproducible.

The generated client's names differ from the hand-written shapes below — that is the cost of generating rather than waiting. The requests and responses are identical, because both come from the one contract.

## List projects

Create `list_projects.py`:

```python
import asyncio
import os

import hlix

async def main() -> None:
    configuration = hlix.Configuration(
        host=os.environ.get("HLIX_BASE_URL", "https://server.hlix.ai")
    )
    configuration.api_key["apiKey"] = os.environ["HLIX_API_KEY"]

    async with hlix.ApiClient(configuration) as api_client:
        projects = await hlix.ProjectsApi(api_client).list_projects(
            x_organization_id=os.environ["HLIX_WORKSPACE_ID"]
        )
        print(projects)

asyncio.run(main())
```

Run it with secret environment variables:

```bash
HLIX_API_KEY='…' \
HLIX_WORKSPACE_ID='<workspace-id>' \
python list_projects.py
```

Expected result: the selected workspace's project collection is printed.

## Authentication and tenancy

The generator names the OpenAPI API-key scheme `apiKey`, which maps to the `x-api-key` header. Pass `x_organization_id` on every call in programmatic use; an API key identifies a user but does not safely imply which workspace automation intended.

## Preview limitations

- Generated names and ergonomics may change before the first stable package release.
- The client does not provide the TypeScript SDK's opinionated error hierarchy, retry policy, CLI snapshot scanner, or high-level local sync workflow.
- Streaming and multi-step bundle protocols need application-level handling and verification.
- Some response bodies remain generic when the published contract does not pin a more specific schema.

## If the preview client fails

- `ModuleNotFoundError`: activate the virtual environment, and import the module name your generator produced — a generated client does not necessarily import as `hlix`.
- `KeyError: HLIX_API_KEY`: provide the secret through your environment or secret manager.
- `401`: the API key is invalid or missing.
- `403`: the user cannot act in `HLIX_WORKSPACE_ID`.
- `404`: the resource is absent or not visible; do not infer cross-tenant existence.
- Dependency resolution error: use Python 3.10+ and install into a fresh virtual environment.
- Generated source differs after regeneration: pin your generator version, and re-download the contract — its `info.version` tells you whether the contract itself moved.

## Next steps

[API & OpenAPI](/api/openapi/)
  [TypeScript SDK](/sdk/typescript/)
  [Go SDK preview](/sdk/go/)
  [Current versions](/releases/availability/)