ionq-core

A client library for accessing IonQ Cloud Platform API.

ionq-core is a typed, async-capable Python client for the IonQ Cloud Platform REST API. The HTTP layer is generated from IonQ's OpenAPI specification with openapi-python-client; a small set of hand-written extensions wraps it with retries, polling, pagination, structured exceptions, and an extension API for downstream SDKs.

The full API reference is published at ionq.github.io/ionq-core-python.

Looking for a higher-level interface?

ionq-core is the low-level HTTP client. Most users should pick the integration that matches their existing stack:

• Qiskit users -> qiskit-ionq
• Cirq users -> cirq-ionq
• PennyLane users -> pennylane-ionq
• CUDA-Q users -> IonQ is configured as a backend in NVIDIA CUDA-Q.
• Multi-vendor users -> IonQ is reachable via qbraid.

Use this package directly if you want programmatic access to the IonQ REST API close to the wire, or if you are building a downstream SDK on top of it.

Installation

pip install ionq-core

Quickstart

Submit a Bell-state circuit on the cloud simulator and read the result probabilities:

from ionq_core import IonQClient, wait_for_job
from ionq_core.api.default import create_job, get_job_probabilities
from ionq_core.models.circuit_job_creation_payload import CircuitJobCreationPayload

client = IonQClient()  # reads IONQ_API_KEY from the environment

body = CircuitJobCreationPayload.from_dict({
    "type": "ionq.circuit.v1",
    "backend": "simulator",
    "shots": 100,
    "input": {
        "gateset": "qis",
        "circuit": [
            {"gate": "h", "targets": [0]},
            {"gate": "cnot", "control": 0, "target": 1},
        ],
    },
})

job = create_job.sync(client=client, body=body)
completed = wait_for_job(client, job.id)
probs = get_job_probabilities.sync(uuid=job.id, client=client)
print(probs.additional_properties)

Each generated endpoint module exposes four callables: sync, sync_detailed, asyncio, and asyncio_detailed. The sync and asyncio variants return the parsed body; the _detailed variants return a Response[T] with the status code, headers, and parsed body.

For options (api_key, base_url, max_retries, timeout, extension), error classes, retry behavior, pagination, polling, sessions, and downstream-SDK extension hooks, see the API reference.

Versioning

This package follows SemVer 2.0, independent of the upstream REST API version - pass an explicit base_url to IonQClient to pin against a different API. Print the installed version with:

import ionq_core
print(ionq_core.__version__)

The full release history is in CHANGELOG.md.

Contributing

Most of ionq_core/ is generated from the OpenAPI spec and overwritten on every regeneration. See CONTRIBUTING.md for the boundary between generated and hand-written code, development setup, and the regeneration command.

Support

• Bug reports and feature requests: GitHub Issues
• Security disclosures: see SECURITY.md
• Account, billing, or hardware-access questions: ionq.com/contact

License

Apache License 2.0. See LICENSE.