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 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 is public and needs no authentication, so you can generate a working Python client now:

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

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:

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 & OpenAPIThe contract lifecycle, regeneration, and the compatibility policy.

TypeScript SDKThe opinionated first-party client, with retries, typed errors, and streaming.

Go SDK previewThe same generated contract, in Go.

Current versionsWhat is published today, and the gate each package still has to pass.