API Reference
Complete reference for the Qubience REST API and Python SDK. Get started in under 5 minutes.
Quick Start
from qubience import QFClient
# Initialize the client
qf = QFClient(api_key="qf_live_your_key")
# Step 1: Validate your circuit (free)
v = qf.validate(circuit_qasm=my_qasm)
print(f"Compatible: {v.compatible}")
print(f"Expected improvement: {v.estimated_improvement}")
# Step 2: Run and correct (main endpoint)
result = qf.run_and_correct(
circuit_qasm=my_qasm,
ibm_token="your_ibm_token",
backend="ibm_fez",
shots=8192,
)
# Step 3: Check results
print(result.corrected_counts)
print(f"Corrected expectation: {result.corrected_expectation}")
print(f"All candidates: {result.all_expectation_candidates}")Authentication
All authenticated endpoints require a Bearer token in the Authorization header. Get your API key from the Qubience Dashboard.
Important
Keep your API key secret. Never expose it in client-side code or public repositories. If compromised, revoke it immediately from the dashboard.
curl -X POST https://api.qubience.com/v1/run_and_correct \
-H "Authorization: Bearer qf_live_..." \
-H "Content-Type: application/json" \
-d '{ "circuit_qasm": "...", "ibm_token": "...", "backend": "ibm_fez" }'Endpoints
/v1/validateTry it freeCheck circuit compatibility (free, no auth required for test)
Request
curl -X POST https://api.qubience.com/v1/validate \
-H "Content-Type: application/json" \
-d '{
"circuit_qasm": "OPENQASM 3; ..."
}'Response
{
"compatible": true,
"num_qubits": 5,
"num_layers": 12,
"num_cx_gates": 42,
"estimated_improvement": "20-40",
"warnings": [],
"recommendation": "Circuit is well-suited for optimization."
}/v1/correctCorrect pre-collected QPU counts (bring your own results)
Request
curl -X POST https://api.qubience.com/v1/correct \
-H "Authorization: Bearer qf_live_..." \
-H "Content-Type: application/json" \
-d '{
"counts": {"00": 3800, "01": 400, "10": 392, "11": 3600},
"n_qubits": 2,
"backend": "ibm_fez"
}'Response
{
"corrected_counts": {"00": 4200, "11": 3992},
"correction_tier": "cal",
"metrics": {"n_qubits": 2, "total_shots": 8192}
}/v1/run_and_correctRun your circuit on IBM hardware and return error-corrected results
Request
curl -X POST https://api.qubience.com/v1/run_and_correct \
-H "Authorization: Bearer qf_live_..." \
-H "Content-Type: application/json" \
-d '{
"circuit_qasm": "OPENQASM 2.0; ...",
"ibm_token": "your_ibm_token",
"backend": "ibm_fez",
"shots": 8192
}'Response
{
"corrected_counts": {"00": 4200, "11": 3992},
"corrected_expectation": 0.93,
"expectation_method": "o-cdr",
"raw_counts": {"00": 3800, "01": 400, "10": 392, "11": 3600},
"metrics": {
"n_qubits": 2,
"correction_tier": "cdr+nec",
"total_qpu_seconds": 12.3
}
}/v1/billing/usageCheck your current usage and plan information
Request
curl https://api.qubience.com/v1/billing/usage \
-H "Authorization: Bearer qf_live_..."Response
{
"plan": "free",
"calls_made": 3,
"calls_remaining": 7,
"calls_limit": 10,
"rate_limit_per_minute": 2,
"max_qubits": 1000,
"current_month": "2026-09"
}/v1/healthAPI health check (public)
Request
curl https://api.qubience.com/v1/healthResponse
{
"status": "healthy",
"service": "qubience",
"version": "0.1.0",
"database": "connected",
"uptime_seconds": 86423
}Error Codes
OK
Request succeeded.
Bad Request
Invalid request body or missing required fields.
Unauthorized
Missing or invalid API key.
Payment Required
Monthly call limit reached. Upgrade your plan for more calls. All algorithms and qubit counts are always available.
Unprocessable Entity
Invalid quantum circuit or unsupported backend.
Too Many Requests
Rate limit exceeded. Wait and retry.
Internal Server Error
Unexpected error. Contact support if persistent.
Python SDK
The official Python SDK wraps the REST API with typed methods, automatic retries, and built-in circuit validation.
pip install qubienceqf.validate()Check circuit compatibility
qf.run_and_correct()Run on QPU and return corrected results
qf.usage()Check plan & usage stats
How It Works
Validate
Check compatibility
Run & Correct
Execute + error correct
Results
Corrected counts & expectations