QCOS™ Network API

"NVLink for QPUs" - Interconnecting Quantum Processors Across Clouds

Overview

The QCOS Network API provides enterprise-grade access to distributed quantum computing capabilities. It enables quantum teleportation, remote entanglement, and multi-cloud orchestration through a simple REST interface.

Base URL: https://api.qcos.io/api/v1/network

Authentication: Bearer token or API key header

# Using Bearer token
curl -H "Authorization: Bearer YOUR_API_KEY" https://api.qcos.io/api/v1/network/health

# Using X-API-Key header
curl -H "X-API-Key: YOUR_API_KEY" https://api.qcos.io/api/v1/network/health

---

Quick Start

1. Check Service Health

curl https://api.qcos.io/api/v1/network/health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "mode": "EMULATED",
  "mode_label": "⚠️ EMULATED MODE - Classical simulation",
  "timestamp": "2026-02-06T10:00:00Z"
}

2. Run Your First Phase 0B Recommendation

curl -X POST https://api.qcos.io/api/v1/network/phase0b/recommend \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "backend_name": "ibm_brisbane",
    "circuit_depth": 10,
    "num_qubits": 5
  }'

Response:

{
  "request_id": "req-abc123",
  "mode": "EMULATED",
  "backend_name": "ibm_brisbane",
  "selected_qubits": [2, 3],
  "predicted_fidelity": 0.975,
  "confidence_interval": [0.955, 0.995],
  "improvement_over_random_pct": 5.98,
  "recommendations": {
    "optimization_level": 3,
    "use_error_mitigation": true,
    "use_dynamical_decoupling": true
  }
}

---

API Endpoints

Phase 0A: Technology Selection

List Ion Species

Returns all supported trapped ion species with physical properties.

GET /api/v1/network/phase0/ion-species

Response:

[
  {
    "species_name": "171Yb+",
    "atomic_number": 70,
    "mass_amu": 170.936,
    "nuclear_spin": "1/2",
    "qubit_type": "hyperfine",
    "t1_seconds": 600.0,
    "t2_seconds": 1.5,
    "single_qubit_gate_fidelity": 0.9999,
    "two_qubit_gate_fidelity": 0.995,
    "providers": ["IonQ", "Quantinuum"]
  }
]

Technology Sweep

Run a comprehensive sweep across 53 hardware configurations.

POST /api/v1/network/phase0/sweep

Request:

{
  "target_fidelity": 0.99,
  "max_qubits": 50,
  "technologies": ["trapped_ion", "superconducting"],
  "include_simulators": true
}

---

Phase 0B: Backend-Aware Planning

Analyze Backend

Get detailed calibration analysis for a specific backend.

POST /api/v1/network/phase0b/analyze

Request:

{
  "backend_name": "ibm_brisbane",
  "circuit_type": "bell_state"
}

Response:

{
  "request_id": "req-xyz789",
  "backend_name": "ibm_brisbane",
  "num_qubits": 127,
  "calibration_age_hours": 2.5,
  "best_qubit_pairs": [
    {"qubits": [2, 3], "cx_error": 0.0045, "readout_error": 0.012}
  ],
  "technology": "superconducting",
  "connectivity": "heavy-hex"
}

Recommend Optimal Qubits

Get AI-powered qubit selection with fidelity prediction.

POST /api/v1/network/phase0b/recommend

Request:

{
  "backend_name": "ibm_brisbane",
  "circuit_depth": 10,
  "num_qubits": 5,
  "optimization_goal": "fidelity"
}

Response:

{
  "request_id": "req-abc123",
  "mode": "EMULATED",
  "mode_label": "⚠️ EMULATED MODE - Classical simulation",
  "backend_name": "ibm_brisbane",
  "selected_qubits": [2, 3, 4, 5, 6],
  "predicted_fidelity": 0.975,
  "confidence_interval": [0.955, 0.995],
  "random_expected_fidelity": 0.92,
  "improvement_over_random_pct": 5.98,
  "recommendations": {
    "optimization_level": 3,
    "use_error_mitigation": true,
    "use_dynamical_decoupling": true,
    "estimated_execution_time_seconds": 12.5
  },
  "evidence_id": "ev-phase0b-abc123"
}

---

Distributed Primitives (QuantumMPI)

Quantum Teleportation

Teleport quantum state between network nodes.

POST /api/v1/network/teleport

Request:

{
  "source_node": "node_alice",
  "target_node": "node_bob",
  "state_description": "arbitrary single-qubit state",
  "use_error_correction": true
}

Response:

{
  "request_id": "req-tel001",
  "mode": "EMULATED",
  "teleport_id": "tp-abc123",
  "status": "completed",
  "source_node": "node_alice",
  "target_node": "node_bob",
  "fidelity": 0.985,
  "classical_bits_sent": 2,
  "entanglement_consumed": 1,
  "total_time_ms": 45.2,
  "evidence_id": "ev-teleport-abc123"
}

Remote CNOT Gate

Execute controlled-NOT gate across network nodes.

POST /api/v1/network/remote-cnot

Request:

{
  "control_node": "node_alice",
  "control_qubit": 0,
  "target_node": "node_bob",
  "target_qubit": 0
}

Entanglement Generation

Generate entangled pairs between nodes.

POST /api/v1/network/entangle

Request:

{
  "node_a": "node_alice",
  "node_b": "node_bob",
  "num_pairs": 10,
  "target_fidelity": 0.95
}

Response:

{
  "request_id": "req-ent001",
  "mode": "EMULATED",
  "entanglement_id": "ent-abc123",
  "status": "completed",
  "node_a": "node_alice",
  "node_b": "node_bob",
  "pairs_requested": 10,
  "pairs_generated": 10,
  "avg_fidelity": 0.962,
  "generation_rate_hz": 1000,
  "total_time_ms": 10.5,
  "evidence_id": "ev-entangle-abc123"
}

Barrier Synchronization

Synchronize operations across multiple nodes.

POST /api/v1/network/barrier

Request:

{
  "nodes": ["node_alice", "node_bob", "node_charlie"],
  "timeout_ms": 1000
}

---

Network Management

Get Network Topology

GET /api/v1/network/topology

Response:

{
  "topology_type": "mesh",
  "num_nodes": 3,
  "num_links": 3,
  "nodes": [
    {
      "node_id": "node_alice",
      "node_type": "compute",
      "status": "online",
      "num_qubits": 10,
      "connected_nodes": ["node_bob", "node_charlie"]
    }
  ],
  "links": [
    {
      "link_id": "link_alice_bob",
      "node_a": "node_alice",
      "node_b": "node_bob",
      "state": "active",
      "technology": "fiber",
      "distance_km": 1.0,
      "avg_fidelity": 0.95
    }
  ]
}

Get Network Status

GET /api/v1/network/status

List Available Backends

Get comprehensive information about all quantum backends.

GET /api/v1/network/backends?include_demo=true

Response:

{
  "total_backends": 10,
  "total_qpu_qubits": 518,
  "total_simulator_qubits": 172,
  "cheapest_qpu": "ibm_brisbane",
  "highest_fidelity_qpu": "quantinuum.qpu.h2-1",
  "fastest_availability_qpu": "ionq.qpu.aria-1",
  "recommended_for_research": ["ibm_sherbrooke", "quantinuum.qpu.h1-1"],
  "recommended_for_production": ["ibm_brisbane", "ionq.qpu.aria-1"],
  "recommended_for_cost_sensitive": ["ibm_brisbane", "ibm_kyiv"],
  "backends": [
    {
      "name": "ibm_brisbane",
      "provider": "IBM Quantum",
      "technology": "superconducting",
      "num_qubits": 127,
      "connectivity": "heavy-hex",
      "two_gate_error": 0.008,
      "pricing_model": "per_shot",
      "estimated_cost_1000_shots": 0.10,
      "typical_queue_minutes": 5
    },
    {
      "name": "quantinuum.qpu.h2-1",
      "provider": "Quantinuum",
      "technology": "trapped_ion",
      "num_qubits": 56,
      "connectivity": "all-to-all",
      "two_gate_error": 0.0008,
      "pricing_model": "per_hqc",
      "estimated_cost_1000_shots": 25.00,
      "typical_queue_minutes": 60
    }
  ]
}

---

Async Jobs

For long-running operations, use the async job system.

Submit Phase 0B Job

POST /api/v1/network/jobs/phase0b?backend_name=ibm_brisbane

Request:

{
  "circuit_depth": 10,
  "num_qubits": 5
}

Response:

{
  "job_id": "job-abc123",
  "request_id": "req-xyz789",
  "status": "pending",
  "job_type": "phase0b_recommend",
  "status_url": "/api/v1/network/jobs/job-abc123/status",
  "estimated_duration_seconds": 10,
  "rate_limit": {
    "tier": "pro",
    "requests_per_minute": {"used": 1, "limit": 60, "remaining": 59}
  }
}

Get Job Status

GET /api/v1/network/jobs/{job_id}/status

Response:

{
  "job_id": "job-abc123",
  "status": "completed",
  "progress_pct": 100,
  "duration_seconds": 0.18,
  "has_result": true,
  "result_url": "/api/v1/network/jobs/job-abc123/result"
}

Get Job Result

GET /api/v1/network/jobs/{job_id}/result

List All Jobs

GET /api/v1/network/jobs?limit=20&offset=0

---

Evidence System

Every operation generates cryptographic evidence for audit trails.

Get Evidence Record

GET /api/v1/network/evidence/{evidence_id}

Get Evidence Bundle

GET /api/v1/network/jobs/{job_id}/evidence

Response:

{
  "job_id": "job-abc123",
  "evidence_id": "evb-xyz789",
  "created_at": "2026-02-06T10:00:00Z",
  "job_type": "phase0b_recommend",
  "input_hash": "sha256:abc123...",
  "output_hash": "sha256:def456...",
  "calibration_snapshot_hash": "sha256:ghi789...",
  "evidence_records": [
    {
      "evidence_id": "ev-step1-abc",
      "operation": "calibration_fetch",
      "timestamp": "2026-02-06T10:00:01Z"
    }
  ],
  "verification_status": "valid",
  "signature": "HMAC-SHA256:..."
}

---

Demo Endpoint

Try the full Phase 0 + Phase 0B pipeline in one call.

POST /api/v1/network/demo/phase0-bell

Request:

{
  "backend_preference": "ibm"
}

Response:

{
  "request_id": "req-demo123",
  "mode": "EMULATED",
  "summary": "QCOS Phase 0 Analysis Complete",
  "phase0_sweep": {
    "technologies_analyzed": 3,
    "best_technology": "trapped_ion",
    "best_technology_fidelity": 0.995
  },
  "phase0b_recommendation": {
    "backend_name": "ibm_brisbane",
    "selected_qubits": [2, 3],
    "predicted_fidelity": 0.975,
    "improvement_pct": 5.98
  },
  "value_proposition": "QCOS improves Bell state fidelity by 5.98% through intelligent qubit selection",
  "evidence_id": "ev-demo-abc123"
}

---

Response Modes

All responses include a mode field indicating the execution context:

Mode	Description
EMULATED	Classical simulation, no physical quantum hardware
NETWORK_ASSISTED	Hybrid execution with classical optimization
DISTRIBUTED	Full distributed quantum execution across nodes

The mode_label field provides a human-readable description with emoji indicators.

---

Error Handling

HTTP Status Codes

Code	Meaning
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions or tier
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Response Format

{
  "detail": "Error message describing the issue",
  "error_code": "INVALID_BACKEND",
  "request_id": "req-abc123"
}

---

Rate Limits

Tier	Requests/Minute	Requests/Hour	QPU Access
Free	10	100	Simulators only
Pro	60	1,000	Simulators + limited QPU
Enterprise	300	10,000	Unlimited

Rate limit information is included in job submission responses.

---

Pricing Estimates

The /backends endpoint provides cost estimates for planning:

Backend	Technology	Cost/1000 shots	Monthly (300K shots)
ibm_brisbane	Superconducting	$0.10	$30
ibm_sherbrooke	Superconducting	$0.12	$36
ionq.qpu.aria-1	Trapped Ion	$1.65	$495
ionq.qpu.forte-1	Trapped Ion	$6.00	$1,800
quantinuum.qpu.h1-1	Trapped Ion	$25.00	$7,500

Prices are estimates and may vary. Check provider documentation for current rates.

---

SDK Examples

Python

import requests

API_KEY = "your-api-key"
BASE_URL = "https://api.qcos.io/api/v1/network"

# Phase 0B Recommendation
response = requests.post(
    f"{BASE_URL}/phase0b/recommend",
    headers={"X-API-Key": API_KEY},
    json={
        "backend_name": "ibm_brisbane",
        "circuit_depth": 10,
        "num_qubits": 5
    }
)

result = response.json()
print(f"Selected qubits: {result['selected_qubits']}")
print(f"Predicted fidelity: {result['predicted_fidelity']:.3f}")
print(f"Improvement: {result['improvement_over_random_pct']:.2f}%")

JavaScript

const API_KEY = 'your-api-key';
const BASE_URL = 'https://api.qcos.io/api/v1/network';

async function getBackends() {
  const response = await fetch(`${BASE_URL}/backends?include_demo=true`, {
    headers: { 'X-API-Key': API_KEY }
  });
  const data = await response.json();

  console.log(`Total backends: ${data.total_backends}`);
  console.log(`Cheapest QPU: ${data.cheapest_qpu}`);
  console.log(`Highest fidelity: ${data.highest_fidelity_qpu}`);
}

cURL

# List backends with recommendations
curl -X GET "https://api.qcos.io/api/v1/network/backends?include_demo=true" \
  -H "X-API-Key: YOUR_API_KEY" | jq '.recommended_for_research'

# Submit async job
curl -X POST "https://api.qcos.io/api/v1/network/jobs/phase0b?backend_name=ibm_brisbane" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"circuit_depth": 10, "num_qubits": 5}'

---

OpenAPI Specification

Full OpenAPI 3.0 specification is available at:

https://api.qcos.io/openapi.json

Interactive documentation (Swagger UI):

https://api.qcos.io/docs

---

Support

• Documentation: https://docs.qcos.io
• API Status: https://status.qcos.io
• Email: support@softquantus.com
• Enterprise Sales: sales@softquantus.com

---

© 2024-2026 SoftQuantus Innovative OÜ. All Rights Reserved.

QCOS™ is a trademark of SoftQuantus Innovative OÜ.