Quantum API Python SDK
The Python SDK is a synchronous, package-ready client for scripts, CLIs, services, and backend automation. It handles the Quantum API's mounted /v1 address and returns structured errors when a request fails.
Runtime / package
Python package
Version
0.1.0
What this SDK is
quantum-api-sdk is a synchronous Python client for scripts, command-line tools, service integrations, and backend automation. It uses httpx and works as a context manager.
Install
pip install quantum-api-sdk
The package requires Python 3.11 or later.
Configure
The base URL is the web address the client sends requests to. You can pass the mounted Quantum API address with or without /v1; the client makes the final address consistent.
from quantum_api_sdk import QuantumApiClient
client = QuantumApiClient(
base_url="https://davidjgrimsley.com/public-facing/api/quantum",
api_key="your-runtime-api-key",
)
First call: Health Check
from quantum_api_sdk import QuantumApiClient, QuantumApiError
with QuantumApiClient(
base_url="https://davidjgrimsley.com/public-facing/api/quantum"
) as client:
try:
health = client.health()
print(health["status"])
except QuantumApiError as error:
print(error.status_code, error.code, error.request_id)
Run Gate example
with QuantumApiClient(
base_url="https://davidjgrimsley.com/public-facing/api/quantum",
api_key="your-runtime-api-key",
) as client:
gate = client.run_gate({
"gate_type": "rotation",
"rotation_angle_rad": 1.57079632679,
})
print(gate["measurement"])
Auth modes
auto
The default. Health and portfolio are public, profile and key routes use bearer auth, and runtime routes use an API key.
api_key
Use X-API-Key for protected runtime methods.
bearer
Use a signed-in user's bearer token for keys and IBM profiles.
none
Use only for public calls such as health.
IBM profiles and jobs
Create and verify IBM profiles with a bearer token, then use the savedibm_profile name in backend, transpile, and job requests. In a distributed app, keep the IBM profile lifecycle on your server.
IBM hardware jobs have to wait in a queue before starting; get started at quantum.cloud.ibm.com.
Useful methods
-
health, portfolio, echo_types, run_gate, run_circuit, transform_text
-
list_backends, transpile, import_qasm, export_qasm, run_qasm
-
list_keys, create_key, revoke_key, rotate_key, delete_key
-
list_ibm_profiles, create_ibm_profile, update_ibm_profile, verify_ibm_profile, delete_ibm_profile
-
submit_circuit_job, submit_qasm_job, submit_random_job, get_circuit_job, get_circuit_job_result, cancel_circuit_job
Troubleshooting
-
Catch QuantumApiError so failures preserve a status code, normalized code, request ID, and details.
-
Use API-key auth for runtime calls and bearer auth for account/profile calls.
-
Keep credentials in environment variables or server-side secret storage, not in a shipped client.
Feedback, contributions, comments, and questions
Questions, corrections, and issue reports are welcome. Email DavidJGrimsley@gmail.com or open an issue at github.com/davidjgrimsley/quantum-api/issues.
Agent version (.md)
Coding agents can use the plain Markdown companion for this guide at /public-facing/api/quantum/python-sdk.md. For best results, also point the agent at /llms.txt so it can discover the core API guide, OpenAPI references, and the other integration guides.