SDK Reference
v0.1.1

Commutator SDK

The Commutator Studios SDK is an intuitive wrapper designed for developers and researchers. Instead of invoking HTTP endpoints manually, you can interact with jobs, optimizer models, and quantum hardware backends natively within your environments.

Installation

Install the official package:

pip install commutator-sdk
Quickstart Example
from commutator import CommutatorClient

client = CommutatorClient(
    api_key="your_api_key"
)

# Start working
jobs = client.jobs.list()

Authentication

Authentication

Initialize API Key

CommutatorClient(api_key: str, base_url: str = None)

Initialize the SDK client using your developer API Key. If not provided, it falls back to the COMMUTATOR_API_KEY environment variable.

Parameters

api_key(string)required
Your public API key starting with cs_live_
base_url(string)
Override target platform address (default is stage/production)
from commutator import CommutatorClient

client = CommutatorClient(api_key="cs_live_abc123...")
Authentication

JWT Login

CommutatorClient.login(email: str, password: str, base_url: str = None)

Alternative method to authenticate using account credentials. Retrieves a temporary secure token.

Parameters

email(string)required
Registered user account email
password(string)required
Account password
from commutator import CommutatorClient

client = CommutatorClient.login(
    email="researcher@university.edu",
    password="secure_password"
)

Jobs Management

Jobs Management

List Jobs

client.jobs.list() -> List[Job]

Retrieve the job list history and status for the authenticated user.

jobs = client.jobs.list()
for job in jobs:
    print(job.id, job.status)
Jobs Management

Create Job

client.jobs.create(name: str, algorithm: str, file_path: str, **kwargs) -> dict

Creates a new quantum job. Returns the Job object with its assigned ID and initial Pending status. Note that this only creates the job from a file; execution configuration happens later unless using a specialized endpoint like submit_vqe.

Parameters

name(string)required
Descriptive name of the quantum job
algorithm(string)required
Algorithm identifier (e.g. "VQE1")
file_path(string)required
Local path to the JSON configuration file.

Expected JSON Format

{
  "circuit_qasm": "OPENQASM 3.0; ...",
  "hamiltonian": [["XXI", 0.5], ["ZZZ", -1.0]],
  "parameters": [0.12, 0.34],
  "metadata": "Optional description"
}
new_job = client.jobs.create(
    name="VQE Hydrogen Molecule",
    algorithm="VQE1",
    file_path="circuit.json"
)
Jobs Management

Execute Job

client.jobs.execute(job_id: str, backend: str, **kwargs) -> dict

Executes a previously created job on the specified quantum backend. Triggers the event-driven orchestrator for routing.

Parameters

job_id(string)required
The ID of the job to execute
backend(string)required
Target quantum backend name
dynamic_decoupling(boolean)
Enable dynamic decoupling (default: False)
optimization_level(integer)
Circuit optimization level (0-3, default: 3)
job_execution = client.jobs.execute(
    job_id=new_job["id"],
    backend="ibm_berlin",
    optimization_level=3
)
Jobs Management

Get Job Details

client.jobs.get(job_id: str) -> Job

Retrieve complete metadata, configuration, and current status of a specific job.

Parameters

job_id(string)required
The unique UUID of the job
job = client.jobs.get("job_8f7d9c2a")
print(job.status) # Returns 'Pending', 'Completed', or 'Failed'
Jobs Management

Cancel Job

client.jobs.cancel(job_id: str) -> bool

Attempt to cancel a pending or queued job. Returns True if successfully cancelled.

Parameters

job_id(string)required
The unique UUID of the job to cancel
success = client.jobs.cancel("job_8f7d9c2a")
print("Cancelled:", success)
Jobs Management

List Algorithms

client.jobs.list_algorithms() -> List[str]

Retrieve the list of supported quantum algorithms available for execution.

algorithms = client.jobs.list_algorithms()
print("Supported:", algorithms)
Jobs Management

Download Results

job.download_results() -> Dict[str, Any]

Download the calculated mathematical eigenvalues or optimized quantum result data.

job = client.jobs.get("job_8f7d9c2a")
results = job.download_results()
print("Energy eigenvalue:", results.get("energy"))

Fleet & Backends

Fleet & Backends

List Backends

client.fleet.list_backends() -> List[Dict]

Query the available quantum processors, physical qubits count, and current availability status.

backends = client.fleet.list_backends()
for backend in backends:
    print(backend["name"], backend["status"])
Fleet & Backends

Discover Backends

client.fleet.discover() -> Dict

Discover detailed topology, calibration data, and capabilities of available backends.

topology = client.fleet.discover()
print("Coupling map:", topology.get("coupling_map"))
Fleet & Backends

Activate Backend

client.fleet.activate(backend_id: str) -> bool

Request exclusive access or activation of a specific reserved backend processor.

Parameters

backend_id(string)required
The unique identifier of the backend
client.fleet.activate("550e8400-e29b-41d4-a716-446655440000")

Optimizer Engine

Optimizer Engine

Get Recommendation

client.optimizer.recommend(execution_id: str, target_backend: str, target_dd: bool = True) -> Dict

Request target backend selection and optimal algorithm parameters based on circuit depth.

Parameters

execution_id(string)required
Target execution ID generated during circuit upload
target_backend(string)required
Proposed target backend processor
target_dd(boolean)
Enable Dynamic Decoupling recommendations
config = client.optimizer.recommend(execution_id='550e8400-e29b-41d4-a716-446655440000', target_dd=True)

Identity & Administration

Identity & Administration

Get Team Details

client.admin.get_team() -> Dict

Retrieve details about your current organization/team and quota limits.

team = client.admin.get_team()
print("Team Name:", team["name"], "Quota:", team["monthly_quota"])
Identity & Administration

List API Keys

client.admin.list_api_keys() -> List[Dict]

Retrieve all active API keys associated with your account.

keys = client.admin.list_api_keys()
for k in keys:
    print(k["name"], k["created_at"])
Identity & Administration

Create API Key

client.admin.create_api_key(name: str, expires_in_days: int = 30) -> str

Generate a new API key for automation or scripts.

Parameters

name(string)required
A descriptive name for the key
expires_in_days(integer)
Key validity duration in days
new_token = client.admin.create_api_key(name="CI Runner", expires_in_days=90)
print("SAVE THIS TOKEN:", new_token)
Identity & Administration

Revoke API Key

client.admin.revoke_api_key(key_id: str) -> bool

Revoke and invalidate an active API key immediately.

Parameters

key_id(string)required
The unique ID of the key to revoke
client.admin.revoke_api_key("key_id_456")
Identity & Administration

Get Audit Logs

client.admin.get_audit_logs(limit: int = 50) -> List[Dict]

Retrieve recent security and access audit logs for the team.

Parameters

limit(integer)
Max number of log entries to retrieve
logs = client.admin.get_audit_logs(limit=10)
for log in logs:
    print(log["action"], log["timestamp"])