API Reference

Complete reference for the Qubience REST API and Python SDK. Get started in under 5 minutes.

Quick Start

Try a correction with synthetic counts first. This uses one included API call and requires no IBM Quantum account. Copy the full API key when creating it; the shortened prefix will not work.

terminal

python -m pip install --upgrade qubience
export QUBIENCE_API_KEY="paste_your_full_key_here"
# Save the Python example as quickstart.py, then run:
python quickstart.py

quickstart.py

import os
from qubience import QFClient

# Set QUBIENCE_API_KEY to the full key shown when you create it.
# These are synthetic example counts; no IBM account is required.
with QFClient(api_key=os.environ["QUBIENCE_API_KEY"]) as qf:
    result = qf.correct(counts={"00": 460, "11": 440, "01": 50, "10": 50})
    print(result.corrected_counts)
    print(result.metrics.correction_tier)

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

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

Requests support 1–200 qubits. Responses below are illustrative excerpts; gains vary by workload. Provider QPU time can be null when unavailable. For queued hardware, set async_mode to true and poll GET /v1/jobs/{job_id} until completed or failed. GET /v1/jobs lists your own jobs. Failed work does not consume a Qubience call; check IBM Workloads before retrying an interrupted job.

POST/v1/validateTry it free

200400422

Check circuit compatibility (free, no auth required for test)

Request

curl

curl -X POST https://api.qubience.com/v1/validate \
  -H "Content-Type: application/json" \
  -d '{
    "circuit_qasm": "OPENQASM 2.0; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;",
    "backend": "ibm_fez"
  }'

Response

response.json

{
  "compatible": true,
  "num_qubits": 5,
  "num_layers": 12,
  "num_cx_gates": 42,
  "estimated_improvement": "20-40",
  "warnings": [],
  "recommendation": "Circuit is well-suited for optimization."
}

POST/v1/correct

200401402422

Correct pre-collected QPU counts (bring your own results)

Request

curl

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

response.json

{
  "corrected_counts": {"00": 4200, "11": 3992},
  "metrics": {"n_qubits": 2, "total_shots": 8192, "correction_tier": "cal_only"}
}

POST/v1/run_and_correct

200401402422

Run your circuit on IBM hardware and return error-corrected results

Request

curl

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; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;",
    "ibm_token": "your_ibm_token",
    "backend": "ibm_fez",
    "shots": 8192,
    "observable": [{"coefficient": 1.0, "pauli": "ZZ"}]
  }'

Response

response.json

{
  "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
  }
}

GET/v1/billing/usage

200401

Check your current usage and plan information

Request

curl

curl https://api.qubience.com/v1/billing/usage \
  -H "Authorization: Bearer qf_live_..."

Response

response.json

{
  "plan": "free",
  "calls_made": 3,
  "calls_remaining": 7,
  "calls_limit": 10,
  "rate_limit_per_minute": 2,
  "max_qubits": 1000,
  "current_month": "2026-09"
}

GET/v1/health

200

API health check (public)

Request

curl

curl https://api.qubience.com/v1/health

Response

response.json

{
  "status": "healthy",
  "service": "qubience",
  "version": "0.1.0",
  "database": "connected",
  "uptime_seconds": 86423
}

Error Codes

200

Request succeeded.

400

Bad Request

Invalid request body or missing required fields.

401

Unauthorized

Missing or invalid API key.

402

Payment Required

Monthly call limit reached. Upgrade your plan for more calls. All plans support requests up to 200 qubits.

422

Unprocessable Entity

Invalid quantum circuit or unsupported backend.

429

Too Many Requests

Rate limit exceeded. Wait and retry.

500

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.

terminal

pip install qubience

qf.validate()

Check circuit compatibility

qf.run_and_correct()

Run on QPU and return corrected results

qf.get_usage()

Check plan & usage stats

How It Works

Validate

Check compatibility

Run & Correct

Execute + error correct

Results

Corrected counts & expectations

import os from qubience import QFClient # Set QUBIENCE_API_KEY to the full key shown when you create it. # These are synthetic example counts; no IBM account is required. with QFClient(api_key=os.environ["QUBIENCE_API_KEY"]) as qf: result = qf.correct(counts={"00": 460, "11": 440, "01": 50, "10": 50}) print(result.corrected_counts) print(result.metrics.correction_tier)

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

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

POST/v1/validateTry it free

200400422

Check circuit compatibility (free, no auth required for test)

Request

curl

curl -X POST https://api.qubience.com/v1/validate \
  -H "Content-Type: application/json" \
  -d '{
    "circuit_qasm": "OPENQASM 2.0; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;",
    "backend": "ibm_fez"
  }'

Response

response.json

{
  "compatible": true,
  "num_qubits": 5,
  "num_layers": 12,
  "num_cx_gates": 42,
  "estimated_improvement": "20-40",
  "warnings": [],
  "recommendation": "Circuit is well-suited for optimization."
}

POST/v1/correct

200401402422

Correct pre-collected QPU counts (bring your own results)

Request

curl

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

response.json

{
  "corrected_counts": {"00": 4200, "11": 3992},
  "metrics": {"n_qubits": 2, "total_shots": 8192, "correction_tier": "cal_only"}
}

POST/v1/run_and_correct

200401402422

Run your circuit on IBM hardware and return error-corrected results

Request

curl

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; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;",
    "ibm_token": "your_ibm_token",
    "backend": "ibm_fez",
    "shots": 8192,
    "observable": [{"coefficient": 1.0, "pauli": "ZZ"}]
  }'

Response

response.json

{
  "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
  }
}

GET/v1/billing/usage

200401

Check your current usage and plan information

Request

curl

curl https://api.qubience.com/v1/billing/usage \
  -H "Authorization: Bearer qf_live_..."

Response

response.json

{
  "plan": "free",
  "calls_made": 3,
  "calls_remaining": 7,
  "calls_limit": 10,
  "rate_limit_per_minute": 2,
  "max_qubits": 1000,
  "current_month": "2026-09"
}

GET/v1/health

200

API health check (public)

Request

curl

curl https://api.qubience.com/v1/health

Response

response.json

{
  "status": "healthy",
  "service": "qubience",
  "version": "0.1.0",
  "database": "connected",
  "uptime_seconds": 86423
}

Error Codes

200

Request succeeded.

400

Bad Request

Invalid request body or missing required fields.

401

Unauthorized

Missing or invalid API key.

402

Payment Required

Monthly call limit reached. Upgrade your plan for more calls. All plans support requests up to 200 qubits.

422

Unprocessable Entity

Invalid quantum circuit or unsupported backend.

429

Too Many Requests

Rate limit exceeded. Wait and retry.

500

Internal Server Error

Unexpected error. Contact support if persistent.