Skip to main content

QCOS™ Network API - Quick Start Guide

Get started with the QCOS Network API in under 5 minutes.

Prerequisites​

Step 1: Verify Your Connection​

export QCOS_API_KEY="your-api-key-here"

curl -H "X-API-Key: $QCOS_API_KEY" \
  https://api.qcos.io/api/v1/network/health

Expected response:

{
  "status": "healthy",
  "version": "1.0.0"
}

Step 2: Explore Available Backends​

See all quantum backends with pricing and recommendations:

curl -H "X-API-Key: $QCOS_API_KEY" \
  "https://api.qcos.io/api/v1/network/backends?include_demo=true"

Key fields in the response:

  • cheapest_qpu - Best value for cost-sensitive workloads
  • highest_fidelity_qpu - Best for research/high-accuracy
  • fastest_availability_qpu - Shortest queue times
  • recommended_for_production - Ready for production workloads

Step 3: Get Your First Qubit Recommendation​

Use Phase 0B to find optimal qubits for your circuit:

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

Response includes:

  • selected_qubits - Optimal qubit indices
  • predicted_fidelity - Expected success rate
  • improvement_over_random_pct - How much better than random selection

Step 4: Try the Demo Endpoint​

Run a complete Phase 0 + Phase 0B analysis:

curl -X POST "https://api.qcos.io/api/v1/network/demo/phase0-bell" \
  -H "X-API-Key: $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"backend_preference": "ibm"}'

This single call demonstrates the full QCOS value proposition.

Step 5: Submit an Async Job​

For long-running operations, use the job system:

# Submit job
JOB_RESPONSE=$(curl -s -X POST \
  "https://api.qcos.io/api/v1/network/jobs/phase0b?backend_name=ibm_brisbane" \
  -H "X-API-Key: $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"circuit_depth": 20, "num_qubits": 10}')

JOB_ID=$(echo $JOB_RESPONSE | jq -r '.job_id')
echo "Job submitted: $JOB_ID"

# Check status
curl -H "X-API-Key: $QCOS_API_KEY" \
  "https://api.qcos.io/api/v1/network/jobs/$JOB_ID/status"

# Get results when completed
curl -H "X-API-Key: $QCOS_API_KEY" \
  "https://api.qcos.io/api/v1/network/jobs/$JOB_ID/result"

Python Quick Start​

import requests

API_KEY = "your-api-key"
BASE = "https://api.qcos.io/api/v1/network"
headers = {"X-API-Key": API_KEY}

# Get backend recommendations
backends = requests.get(f"{BASE}/backends", headers=headers).json()
print(f"Best value: {backends['cheapest_qpu']}")
print(f"Highest fidelity: {backends['highest_fidelity_qpu']}")

# Get qubit recommendation
result = requests.post(
    f"{BASE}/phase0b/recommend",
    headers=headers,
    json={
        "backend_name": backends['cheapest_qpu'],
        "circuit_depth": 10,
        "num_qubits": 5
    }
).json()

print(f"Use qubits: {result['selected_qubits']}")
print(f"Expected fidelity: {result['predicted_fidelity']:.1%}")

Next Steps​

Common Issues​

401 Unauthorized​

Your API key is invalid or missing. Check that you're including it in the header.

429 Too Many Requests​

You've exceeded your rate limit. Upgrade your tier or wait before retrying.

Empty backends list​

Set include_demo=true to see demo data if you haven't configured cloud credentials.

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