QCOS Glass-Box API v2.0 🔬

Version: 3.1.0 Last Updated: February 2, 2026 Patent: FR2513440 Base Path: /api/v2/glassbox

Overview

The Glass-Box API provides complete transparency for quantum circuit execution, enabling:

Phase 1: Real-time device calibration tracking
Phase 2: Hardware-aware multi-objective compilation
Phase 3: Cryptographic evidence bundles with audit trails

This API is essential for regulatory compliance, scientific reproducibility, and enterprise auditing.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Glass-Box API v2.0                          │
├─────────────────────────────────────────────────────────────────┤
│  Phase 1: DeviceState      │  Real-time calibration tracking    │
│  Phase 2: Compiler         │  Multi-objective optimization      │
│  Phase 3: Evidence         │  Cryptographic audit trails        │
└─────────────────────────────────────────────────────────────────┘

Phase 1: Device State API

Track real-time quantum device calibrations with cryptographic hashes.

List Available Devices

GET /api/v2/glassbox/devices

Response:

{
  "devices": [
    {
      "name": "ibm_kyoto",
      "provider": "IBM",
      "num_qubits": 127,
      "status": "online",
      "last_calibration": "2026-02-02T10:30:00Z"
    },
    {
      "name": "ibm_osaka",
      "provider": "IBM",
      "num_qubits": 127,
      "status": "online"
    }
  ],
  "total": 5
}

Get Device Calibration State

GET /api/v2/glassbox/devices/{device_name}/state

Example:

curl https://api.softquantus.com/api/v2/glassbox/devices/ibm_kyoto/state \
  -H "Authorization: Bearer $QCOS_API_KEY"

Response:

{
  "device_name": "ibm_kyoto",
  "state_id": "state-abc123",
  "num_qubits": 127,
  "calibration_timestamp": "2026-02-02T10:30:00Z",
  "state_hash": "3e8673319edfd4fb92c4612aab6fbe73...",
  "qubit_summary": {
    "avg_t1_us": 154.8,
    "avg_t2_us": 79.8,
    "avg_readout_error": 0.012,
    "avg_gate_error": 0.0008
  },
  "connectivity": {
    "total_edges": 144,
    "avg_cx_error": 0.0089
  }
}

Get Qubit Properties

GET /api/v2/glassbox/devices/{device_name}/qubits/{qubit_id}

Response:

{
  "qubit_id": 0,
  "t1_us": 167.3,
  "t2_us": 89.2,
  "readout_error": 0.0098,
  "gate_errors": {
    "x": 0.00034,
    "sx": 0.00021,
    "rz": 0.0
  },
  "frequency_ghz": 5.123,
  "anharmonicity_ghz": -0.321
}

Phase 2: Hardware-Aware Compilation

Compile circuits with multi-objective optimization considering real device calibrations.

Compile Circuit

POST /api/v2/glassbox/compile
Content-Type: application/json

Request:

{
  "qasm": "OPENQASM 2.0;\ninclude \"qelib1.inc\";\nqreg q[5];\nh q[0];\ncx q[0],q[1];\ncx q[1],q[2];",
  "target_device": "ibm_kyoto",
  "optimization_level": 2,
  "objectives": {
    "fidelity": 0.6,
    "depth": 0.3,
    "gate_count": 0.1
  }
}

Response:

{
  "compilation_id": "comp-252db3050cb3",
  "status": "completed",
  "original_circuit_hash": "a1b2c3d4...",
  "compiled_circuit": "OPENQASM 2.0;\n...",
  "compiled_circuit_hash": "e5f6g7h8...",
  "target_device": "ibm_kyoto",
  "device_state_id": "state-abc123",
  "metrics": {
    "original_depth": 4,
    "compiled_depth": 6,
    "original_gate_count": 8,
    "compiled_gate_count": 12,
    "original_two_qubit_count": 2,
    "compiled_two_qubit_count": 4,
    "swap_count": 2,
    "estimated_fidelity": 0.7668,
    "compilation_time_ms": 49.38
  },
  "qubit_mapping": {
    "0": 15,
    "1": 16,
    "2": 17,
    "3": 23,
    "4": 24
  },
  "created_at": "2026-02-02T10:35:00Z"
}

Get Compilation Result

GET /api/v2/glassbox/compile/{compilation_id}

Phase 3: Evidence Bundle API

Create cryptographically signed evidence bundles for complete audit trails.

Create Evidence Bundle

POST /api/v2/glassbox/evidence/create
Content-Type: application/json

Request:

{
  "job_id": "job-12345",
  "circuit_hash": "a1b2c3d4...",
  "device_state_id": "state-abc123",
  "compilation_id": "comp-252db3050cb3",
  "metadata": {
    "experiment": "VQE optimization",
    "researcher": "lab-quantum-01"
  }
}

Response:

{
  "bundle_id": "e510913f-068d-461f-9f9d-498de0b37f03",
  "job_id": "job-12345",
  "version": "2.0",
  "status": "created",
  "created_at": "2026-02-02T10:40:00Z",
  "evidence_items": []
}

Add Evidence to Bundle

POST /api/v2/glassbox/evidence/{bundle_id}/add
Content-Type: application/json

Request:

{
  "evidence_type": "execution_result",
  "data": {
    "counts": {"00": 512, "11": 512},
    "shots": 1024,
    "execution_time_ms": 1250
  }
}

Finalize Bundle

POST /api/v2/glassbox/evidence/{bundle_id}/finalize

Response:

{
  "bundle_id": "e510913f-068d-461f-9f9d-498de0b37f03",
  "status": "finalized",
  "bundle_hash": "d2df91600a1f6e8848363597da5ee5a1...",
  "merkle_root": "2e1cfa82b035c26cbbbdae632cea0705...",
  "finalized_at": "2026-02-02T10:45:00Z",
  "evidence_count": 4
}

Sign Bundle (QuantumLock)

POST /api/v2/glassbox/evidence/{bundle_id}/sign
Content-Type: application/json

Request:

{
  "algorithm": "ECDSA-P256"
}

Response:

{
  "signature_id": "b586a8b1-d6db-4505-828b-eabb79a6d778",
  "bundle_id": "e510913f-068d-461f-9f9d-498de0b37f03",
  "algorithm": "ECDSA-P256",
  "key_id": "289eafef-0ab2-429a-bf71-cfca9c049a15",
  "signed_at": "2026-02-02T10:46:00Z",
  "data_hash": "d2df91600a1f6e8848363597da5ee5a1...",
  "signature_value": "MEUCIQDx7...",
  "public_key_pem": "-----BEGIN PUBLIC KEY-----\n..."
}

Verify Signature

POST /api/v2/glassbox/evidence/verify
Content-Type: application/json

Request:

{
  "bundle_hash": "d2df91600a1f6e8848363597da5ee5a1...",
  "signature_value": "MEUCIQDx7...",
  "public_key_pem": "-----BEGIN PUBLIC KEY-----\n..."
}

Response:

{
  "is_valid": true,
  "verified_at": "2026-02-02T10:47:00Z",
  "message": "Signature is valid"
}

Get Audit Trail

GET /api/v2/glassbox/evidence/{bundle_id}/audit-trail

Response:

{
  "bundle_id": "e510913f-068d-461f-9f9d-498de0b37f03",
  "events": [
    {
      "event_type": "bundle_created",
      "timestamp": "2026-02-02T10:40:00Z",
      "details": {"job_id": "job-12345"}
    },
    {
      "event_type": "evidence_added",
      "timestamp": "2026-02-02T10:42:00Z",
      "details": {"evidence_type": "execution_result"}
    },
    {
      "event_type": "bundle_finalized",
      "timestamp": "2026-02-02T10:45:00Z",
      "details": {"merkle_root": "2e1cfa82..."}
    },
    {
      "event_type": "signature_added",
      "timestamp": "2026-02-02T10:46:00Z",
      "details": {"algorithm": "ECDSA-P256", "key_id": "289eafef..."}
    }
  ],
  "total_events": 4
}

Health & Info Endpoints

Health Check

GET /api/v2/glassbox/health

Response:

{
  "status": "healthy",
  "version": "2.0.0",
  "components": {
    "device_state": "operational",
    "compiler": "operational",
    "evidence": "operational"
  }
}

API Info

GET /api/v2/glassbox/info

Response:

{
  "name": "QCOS Glass-Box API",
  "version": "2.0.0",
  "description": "Transparent quantum circuit execution with cryptographic evidence",
  "patent": "FR2513440",
  "features": ["phase_1", "phase_2", "phase_3"],
  "supported_devices": ["ibm_kyoto", "ibm_osaka", "ibm_brisbane"],
  "supported_algorithms": ["ECDSA-P256", "ECDSA-P384", "RSA-SHA256"]
}

Complete Workflow Example

import httpx

BASE = "https://api.softquantus.com/api/v2/glassbox"
headers = {"Authorization": "Bearer sk_live_..."}

# 1. Get device calibration
state = httpx.get(f"{BASE}/devices/ibm_kyoto/state", headers=headers).json()
print(f"Device state hash: {state['state_hash']}")

# 2. Compile circuit with calibration awareness
compile_resp = httpx.post(f"{BASE}/compile", headers=headers, json={
    "qasm": "OPENQASM 2.0;\ninclude \"qelib1.inc\";\nqreg q[5];\nh q[0];\ncx q[0],q[1];",
    "target_device": "ibm_kyoto",
    "optimization_level": 2
}).json()
print(f"Estimated fidelity: {compile_resp['metrics']['estimated_fidelity']:.2%}")

# 3. Create evidence bundle
bundle = httpx.post(f"{BASE}/evidence/create", headers=headers, json={
    "job_id": "job-12345",
    "circuit_hash": compile_resp['original_circuit_hash'],
    "device_state_id": state['state_id'],
    "compilation_id": compile_resp['compilation_id']
}).json()

# 4. Finalize and sign
httpx.post(f"{BASE}/evidence/{bundle['bundle_id']}/finalize", headers=headers)
signature = httpx.post(f"{BASE}/evidence/{bundle['bundle_id']}/sign", headers=headers, json={
    "algorithm": "ECDSA-P256"
}).json()

print(f"✅ Bundle signed: {signature['signature_id']}")

# 5. Verify signature
verify = httpx.post(f"{BASE}/evidence/verify", headers=headers, json={
    "bundle_hash": signature['data_hash'],
    "signature_value": signature['signature_value'],
    "public_key_pem": signature['public_key_pem']
}).json()

print(f"Signature valid: {verify['is_valid']}")

Supported Signing Algorithms

Algorithm	Key Size	Use Case
ECDSA-P256	256-bit	Default, fast, widely supported
ECDSA-P384	384-bit	Higher security
RSA-SHA256	2048-bit	Legacy compatibility

Error Codes

Code	Description
400	Invalid request (bad QASM, missing fields)
404	Resource not found (device, bundle, compilation)
409	Conflict (bundle already finalized)
500	Internal server error

Rate Limits

Tier	Requests/min	Evidence Bundles/day
Free	10	100
Professional	100	1,000
Enterprise	1,000	Unlimited

Overview​

Architecture​

Phase 1: Device State API​

List Available Devices​

Get Device Calibration State​

Get Qubit Properties​

Phase 2: Hardware-Aware Compilation​

Compile Circuit​

Get Compilation Result​

Phase 3: Evidence Bundle API​

Create Evidence Bundle​

Add Evidence to Bundle​

Finalize Bundle​

Sign Bundle (QuantumLock)​

Verify Signature​

Get Audit Trail​

Health & Info Endpoints​

Health Check​

API Info​

Complete Workflow Example​

Supported Signing Algorithms​

Error Codes​

Rate Limits​

Related Documentation​

Overview

Architecture

Phase 1: Device State API

List Available Devices

Get Device Calibration State

Get Qubit Properties

Phase 2: Hardware-Aware Compilation

Compile Circuit

Get Compilation Result

Phase 3: Evidence Bundle API

Create Evidence Bundle

Add Evidence to Bundle

Finalize Bundle

Sign Bundle (QuantumLock)

Verify Signature

Get Audit Trail

Health & Info Endpoints

Health Check

API Info

Complete Workflow Example

Supported Signing Algorithms

Error Codes

Rate Limits

Related Documentation