Kipu Quantum Hub API SDK

At a glance

• Purpose: multi-language clients for the Kipu Quantum Hub REST APIs - submit quantum jobs and manage sessions, list and inspect backends, catalog and share services and data pools, execute managed services, and read user profiles.
• Packages: qhub-api (Python ≥ 3.9, pip install qhub-api), @quantum-hub/qhub-api (Node ≥ 18 / ESM, npm install @quantum-hub/qhub-api).
• Entry points: HubQuantumClient, HubPlatformClient, HubServiceClient, HubUserClient - one per API surface, identical class names in both languages.
• Use it when: you need to talk to the Quantum Hub programmatically instead of through the dashboard or qhubctl CLI - for example, orchestrating jobs from a notebook, wiring the Hub into an application, or scripting catalog management.
• Pairs with: the qhubctl CLI (shares the same config file and env vars), the Quantum Hub dashboard, and the public docs site.
• Quick reference: HubQuantumClient(api_key=...).jobs.create_job(backend_id, shots, input) -> Job, then jobs.get_job_status(id) / jobs.get_job_result(id).
• New here? Start with Installation, then jump to the client you need.

The SDK wraps four independent APIs that together make up the Kipu Quantum Hub. Each API has its own client class because the four surfaces have distinct auth flows, base URLs, and scopes - you pick the client that matches the work you are doing.

Capabilities exposed by the SDK:

• Submit quantum jobs to any supported backend and stream their results.
• Open sessions for batched or dedicated runs and drive them to completion.
• List and inspect backends, including calibration, configuration, and the least-busy backend for a provider.
• Browse the service catalog, manage service definitions, share services and data pools, and trigger managed or workflow service executions.
• Read organization, subscription, application, data-pool, grant, billing, and notification resources on the platform.
• Invoke deployed services through the service gateway using short-lived bearer tokens.
• Read user profiles, manage personal access tokens, and resolve the currently-authenticated user.

Packages shipped:

Package	Language	Install
qhub-api	Python	pip install qhub-api
@quantum-hub/qhub-api	TypeScript / JavaScript	npm install @quantum-hub/qhub-api

Both packages are generated from the same Fern/OpenAPI definitions and ship the same four clients and the same DTOs. Field casing differs per API (see each client's Reference section).

Installation

The Python package targets Python ≥ 3.9 and depends on httpx and pydantic. The TypeScript package is published as an ESM-only module with native-fetch transport, so it works on Node ≥ 18 and modern browsers.

pip install --upgrade qhub-api

The TypeScript package exposes one entry point per API via subpath exports. Imports are always @quantum-hub/qhub-api/quantum, @quantum-hub/qhub-api/platform, @quantum-hub/qhub-api/service, or @quantum-hub/qhub-api/user; there is no top-level bundle export.

The SDK clients

The reference is split into one page per client. Pick the client that matches the API surface you are working with; the shared install, credential, and environment-variable material below applies to all four.

Client	Page	Auth	Use it for
HubQuantumClient	Quantum API	API key (X-Auth-Token)	Submit jobs, drive sessions, inspect backends.
HubPlatformClient	Platform API	API key (X-Auth-Token)	Catalog: services, applications, organizations, data pools, billing.
HubServiceClient	Service API	Bearer token	Invoke deployed services through the gateway.
HubUserClient	User API	API key (X-Auth-Token)	Read user profiles, manage personal access tokens.

Python credential helpers

The qhub.api.credentials module exposes CredentialProvider implementations you can compose to resolve a token for any of the four clients. Every helper returns the access token string; wire it into the client by passing api_key=<token> (Quantum, Platform, User) or token=<token> (Service).

Provider	Where it looks
StaticCredential(token)	The value you pass in.
EnvironmentCredential()	KQH_SERVICE_EXECUTION_TOKEN, then KQH_PERSONAL_ACCESS_TOKEN, then legacy PLANQK_SERVICE_EXECUTION_TOKEN, SERVICE_EXECUTION_TOKEN, PLANQK_PERSONAL_ACCESS_TOKEN.
ConfigFileCredential()	JSON file at KQH_CONFIG_FILE_PATH env var, else PLANQK_CONFIG_FILE_PATH, else ~/.config/qhubctl/config.json (%LOCALAPPDATA%\qhubctl\config.json on Windows), falling back to the legacy planqk path. Expects {"auth": {"value": "<token>"}}.
DefaultCredentialsProvider(access_token=None)	Tries StaticCredential, then EnvironmentCredential, then ConfigFileCredential, in that order.

If no credential can be resolved, every helper raises CredentialUnavailableError.

from qhub.api.credentials import DefaultCredentialsProvider
from qhub.api.quantum import HubQuantumClient

token = DefaultCredentialsProvider().get_access_token()
client = HubQuantumClient(api_key=token)

Environment variables

Variable	Purpose
KQH_SERVICE_EXECUTION_TOKEN	Service execution token; preferred token env var.
KQH_PERSONAL_ACCESS_TOKEN	Personal access token.
KQH_CONFIG_FILE_PATH	Override the path to the shared config file.
KQH_ORGANIZATION_ID	Default organization id for ContextResolver.
PLANQK_SERVICE_EXECUTION_TOKEN / SERVICE_EXECUTION_TOKEN / PLANQK_PERSONAL_ACCESS_TOKEN	Legacy token env vars, still honoured.
PLANQK_CONFIG_FILE_PATH	Legacy config-file env var, still honoured.
PLANQK_ORGANIZATION_ID	Legacy organization-id env var, still honoured.

None of these are auto-consumed by client constructors - use DefaultCredentialsProvider (Python) or read process.env yourself (TypeScript).