API Reference v2.1

Complete REST API reference for QCOS API v2.1 with multi-supplier support.

Base URL

https://sqt-prod-azure-api-ca.icybay-7dfb32ea.westeurope.azurecontainerapps.io

Production (recommended):

https://api.softquantus.com

Authentication

All endpoints require authentication via API key:

# Header method (recommended)
X-API-Key: your-api-key

# Bearer token method
Authorization: Bearer your-api-key

Suppliers

QCOS v2.1 supports 3 major quantum suppliers with 17+ quantum providers:

Supplier	Providers	Qubits	Status
Azure Quantum	IonQ, Rigetti, Quantinuum, PASQAL	29-100	✅ Active
IBM Quantum	Simulators, Kyoto, Osaka, Brisbane	127	✅ Active
AWS Braket	SV1, IonQ, Rigetti, QuEra, OQC, IQM	8-256	✅ Active

Azure Quantum Endpoints

List Azure Quantum Providers

GET /api/v1/azure_quantum/providers

List all available Azure Quantum providers.

Response:

{
  "providers": [
    {
      "id": "ionq",
      "name": "IonQ",
      "num_qubits": 29,
      "targets": ["ionq.aria", "ionq.harmony", "ionq.simulator"],
      "description": "Trapped-ion quantum computer with all-to-all connectivity",
      "cost_model": "per_aqt"
    },
    {
      "id": "rigetti",
      "name": "Rigetti Computing",
      "num_qubits": 79,
      "targets": ["rigetti.aspen-m-3", "rigetti.simulator"],
      "description": "Superconducting quantum computer",
      "cost_model": "per_second"
    },
    {
      "id": "quantinuum",
      "name": "Quantinuum",
      "num_qubits": 56,
      "targets": ["quantinuum.h1-1", "quantinuum.h1-2", "quantinuum.h2-1"],
      "description": "Highest fidelity trapped-ion QPU",
      "cost_model": "hqc_credits"
    },
    {
      "id": "pasqal",
      "name": "PASQAL",
      "num_qubits": 100,
      "targets": ["pasqal.fresnel", "pasqal.emulator"],
      "description": "Neutral atom quantum computer",
      "cost_model": "per_hour"
    }
  ]
}

Execute on Azure Quantum

POST /api/v1/azure_quantum/execute

Execute circuit on Azure Quantum provider.

Request Body:

{
  "qasm": "OPENQASM 2.0; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;",
  "provider": "ionq",
  "target": "ionq.simulator",
  "shots": 1024
}

Response:

{
  "job_id": "azure_abc123",
  "status": "queued",
  "provider": "ionq",
  "target": "ionq.simulator",
  "estimated_cost": 0.0
}

Get Azure Quantum Job Status

GET /api/v1/azure_quantum/status/{job_id}

Response:

{
  "job_id": "azure_abc123",
  "status": "completed",
  "result": {
    "counts": {"00": 512, "11": 512},
    "shots": 1024
  }
}

Estimate Azure Quantum Cost

POST /api/v1/azure_quantum/estimate

Request Body:

{
  "qasm": "OPENQASM 2.0; ...",
  "provider": "ionq",
  "target": "ionq.aria",
  "shots": 1024
}

Response:

{
  "provider": "ionq",
  "target": "ionq.aria",
  "estimated_cost_usd": 1.25,
  "currency": "USD",
  "cost_breakdown": {
    "aqt": 250,
    "rate_per_aqt": 0.005
  }
}

IBM Quantum Endpoints

List IBM Quantum Backends

GET /api/v1/ibm_quantum/backends

List available IBM Quantum backends.

Response:

{
  "backends": [
    {
      "name": "ibm_simulator",
      "num_qubits": 127,
      "type": "simulator",
      "status": "available",
      "cost": "free"
    },
    {
      "name": "ibm_kyoto",
      "num_qubits": 127,
      "type": "qpu",
      "status": "available",
      "processor": "Eagle r1"
    },
    {
      "name": "ibm_osaka",
      "num_qubits": 127,
      "type": "qpu",
      "status": "available",
      "processor": "Eagle r1"
    },
    {
      "name": "ibm_brisbane",
      "num_qubits": 127,
      "type": "qpu",
      "status": "available",
      "processor": "Eagle r1"
    }
  ]
}

Execute on IBM Quantum

POST /api/v1/ibm_quantum/execute

Request Body:

{
  "qasm": "OPENQASM 2.0; ...",
  "backend": "ibm_simulator",
  "shots": 1024
}

Response:

{
  "job_id": "ibm_xyz789",
  "status": "queued",
  "backend": "ibm_simulator"
}

Get IBM Quantum Job Status

GET /api/v1/ibm_quantum/status/{job_id}

Response:

{
  "job_id": "ibm_xyz789",
  "status": "completed",
  "backend": "ibm_simulator",
  "result": {
    "counts": {"00": 512, "11": 512},
    "shots": 1024,
    "execution_time": 0.15
  }
}

Estimate IBM Quantum Cost

POST /api/v1/ibm_quantum/estimate

Request Body:

{
  "qasm": "OPENQASM 2.0; ...",
  "backend": "ibm_kyoto",
  "shots": 1024
}

Response:

{
  "backend": "ibm_kyoto",
  "estimated_cost_qsh": 1.5,
  "quantum_seconds": 0.5,
  "shots": 1024
}

AWS Braket Endpoints

List Braket Devices

GET /api/v1/braket/devices

List all AWS Braket quantum devices.

Response:

{
  "devices": [
    {
      "arn": "arn:aws:braket:::device/quantum-simulator/amazon/sv1",
      "name": "SV1",
      "type": "simulator",
      "num_qubits": 34,
      "status": "ONLINE"
    },
    {
      "arn": "arn:aws:braket:::device/quantum-simulator/amazon/tn1",
      "name": "TN1",
      "type": "simulator",
      "num_qubits": 50,
      "status": "ONLINE"
    },
    {
      "arn": "arn:aws:braket:us-east-1::device/qpu/ionq/Aria-1",
      "name": "IonQ Aria",
      "type": "qpu",
      "num_qubits": 25,
      "status": "ONLINE"
    },
    {
      "arn": "arn:aws:braket:us-east-1::device/qpu/rigetti/Aspen-M-3",
      "name": "Rigetti Aspen-M-3",
      "type": "qpu",
      "num_qubits": 79,
      "status": "ONLINE"
    },
    {
      "arn": "arn:aws:braket:us-east-1::device/qpu/quera/Aquila",
      "name": "QuEra Aquila",
      "type": "qpu",
      "num_qubits": 256,
      "status": "ONLINE",
      "note": "Neutral atom system - 256 qubits!"
    }
  ]
}

Execute on AWS Braket

POST /api/v1/braket/execute

Request Body:

{
  "qasm": "OPENQASM 2.0; ...",
  "device_arn": "arn:aws:braket:::device/quantum-simulator/amazon/sv1",
  "shots": 1024,
  "s3_bucket": "my-braket-results",
  "s3_prefix": "results/"
}

Response:

{
  "task_id": "braket_task_123",
  "status": "QUEUED",
  "device": "SV1",
  "shots": 1024
}

Get Braket Task Status

GET /api/v1/braket/status/{task_id}

Response:

{
  "task_id": "braket_task_123",
  "status": "COMPLETED",
  "device": "SV1",
  "result": {
    "counts": {"00": 512, "11": 512},
    "shots": 1024
  },
  "s3_result_location": "s3://my-bucket/results/task_123.json"
}

Estimate Braket Cost

POST /api/v1/braket/estimate

Request Body:

{
  "qasm": "OPENQASM 2.0; ...",
  "device_arn": "arn:aws:braket:us-east-1::device/qpu/ionq/Aria-1",
  "shots": 1024
}

Response:

{
  "device": "IonQ Aria",
  "estimated_cost_usd": 0.30,
  "pricing": {
    "per_shot": 0.00030,
    "shots": 1024
  }
}

Legacy Execute Endpoint (LUMI)

GPU-accelerated execution on LUMI supercomputer.

POST /execute

Request Body:

{
  "qasm": "OPENQASM 2.0; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;",
  "shots": 1024,
  "job_id": "optional-custom-id"
}

Response:

{
  "job_id": "lumi_abc123",
  "status": "queued",
  "message": "Job queued for GPU execution on LUMI",
  "estimated_time_seconds": 30,
  "backend": "cuStateVec"
}

Get Job Status (Legacy)

GET /status/{job_id}

Response:

{
  "job_id": "lumi_abc123",
  "status": "completed",
  "result": {
    "counts": {"00": 512, "11": 512},
    "num_qubits": 2,
    "shots": 1024,
    "execution_time_seconds": 0.05,
    "backend": "cuStateVec",
    "device": "NVIDIA A100"
  },
  "created_at": "2025-12-21T10:30:00Z",
  "completed_at": "2025-12-21T10:30:02Z"
}

Health & Status

API Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "2.1.0",
  "suppliers": {
    "azure_quantum": "configured",
    "ibm_quantum": "needs_token",
    "braket": "configured"
  }
}

Supplier Status

GET /api/v1/suppliers/status

Response:

{
  "total_suppliers": 3,
  "enabled_suppliers": 3,
  "configured_suppliers": 2,
  "total_providers": 17,
  "suppliers": [
    {
      "id": "azure_quantum",
      "name": "Azure Quantum",
      "configured": true,
      "providers": [
        {"id": "ionq", "name": "IonQ", "num_qubits": 29, "status": "available"},
        {"id": "rigetti", "name": "Rigetti Computing", "num_qubits": 79, "status": "available"}
      ]
    }
  ]
}

Error Responses

All errors follow this format:

{
  "detail": "Error message",
  "error_code": "ERROR_CODE",
  "supplier": "azure_quantum",
  "request_id": "req_abc123"
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request - Invalid circuit or parameters
401	Unauthorized - Missing or invalid API key
403	Forbidden - Insufficient permissions
404	Not Found - Job/resource not found
422	Unprocessable Entity - Validation error
429	Rate Limited
500	Server Error
503	Service Unavailable - Supplier down

Error Codes

Code	Description
`AUTH_REQUIRED`	No API key provided
`AUTH_INVALID`	Invalid API key
`SUPPLIER_NOT_CONFIGURED`	Supplier credentials missing
`PROVIDER_UNAVAILABLE`	Provider offline or maintenance
`CIRCUIT_INVALID`	Invalid OpenQASM syntax
`QUBITS_EXCEEDED`	Circuit exceeds provider qubit limit
`SHOTS_EXCEEDED`	Shots exceed provider limit
`JOB_NOT_FOUND`	Job ID not found
`JOB_FAILED`	Execution failed
`BACKEND_ERROR`	Supplier backend error

Rate Limits

Rate limits apply per API key:

Tier	Requests/Minute	Jobs/Day	Max Qubits
Free	10	10	20
Pro	60	100	50
Enterprise	300	Unlimited	256

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1734796800

Interactive Documentation

Interactive API documentation available at:

Swagger UI: https://sqt-prod-azure-api-ca.icybay-7dfb32ea.westeurope.azurecontainerapps.io/docs
ReDoc: https://sqt-prod-azure-api-ca.icybay-7dfb32ea.westeurope.azurecontainerapps.io/redoc
OpenAPI JSON: https://sqt-prod-azure-api-ca.icybay-7dfb32ea.westeurope.azurecontainerapps.io/openapi.json

SDKs & Libraries

Language	Package	Version	Install
Python	softqcos-sdk	2.1.0	`pip install softqcos-sdk==2.1.0`

Python SDK Example

from softqcos_sdk import QCOSClient

client = QCOSClient(api_key="your-key")

# List Azure Quantum providers
providers = client.list_providers("azure_quantum")

# Execute on specific backend
result = client.execute_on_backend(
    qasm="OPENQASM 2.0; ...",
    backend="ionq",
    supplier="azure_quantum",
    shots=1024
)

print(result.counts)

See SDK Documentation for full details.

Provider Comparison

Provider	Supplier	Qubits	Type	Connectivity	Best For
IonQ Aria	Azure/Braket	29	Trapped Ion	All-to-all	High fidelity
Quantinuum H1	Azure	56	Trapped Ion	All-to-all	Highest fidelity
Rigetti Aspen-M-3	Azure/Braket	79	Superconducting	Limited	Fast gates
IBM Kyoto	IBM	127	Superconducting	Heavy-hex	Large circuits
QuEra Aquila	Braket	256	Neutral Atom	2D grid	Many qubits
PASQAL Fresnel	Azure	100	Neutral Atom	2D grid	Analog QC

Cost Optimization Tips

Use simulators first - Free on IBM, cheap on Azure/Braket
Start with small shots - Test with 100 shots before full 1024
Compare costs - Same provider may have different pricing across suppliers
Batch jobs - Submit multiple circuits together
Use cost estimation - Always call /estimate endpoint first

Migration from v1.x

v2.1 is backward compatible. Legacy /execute endpoint still works.

New features:

Multi-supplier support (Azure, IBM, Braket)
17+ quantum providers
Provider-specific endpoints
Cost estimation
Backend selection

Breaking changes:

None! Old code continues to work.

Support

Documentation: https://docs.softquantus.com
Changelog: https://docs.softquantus.com/changelog
Email: support@softquantus.com
Status Page: https://status.softquantus.com

Base URL​

Authentication​

Suppliers​

Azure Quantum Endpoints​

List Azure Quantum Providers​

Execute on Azure Quantum​

Get Azure Quantum Job Status​

Estimate Azure Quantum Cost​

IBM Quantum Endpoints​

List IBM Quantum Backends​

Execute on IBM Quantum​

Get IBM Quantum Job Status​

Estimate IBM Quantum Cost​

AWS Braket Endpoints​

List Braket Devices​

Execute on AWS Braket​

Get Braket Task Status​

Estimate Braket Cost​

Legacy Execute Endpoint (LUMI)​

Legacy Execute Endpoint (LUMI)​

Get Job Status (Legacy)​

Health & Status​

API Health Check​

Supplier Status​

Error Responses​

HTTP Status Codes​

Error Codes​

Rate Limits​

Interactive Documentation​

SDKs & Libraries​

Python SDK Example​

Provider Comparison​

Cost Optimization Tips​

Migration from v1.x​

Support​

Base URL

Authentication

Suppliers

Azure Quantum Endpoints

List Azure Quantum Providers

Execute on Azure Quantum

Get Azure Quantum Job Status

Estimate Azure Quantum Cost

IBM Quantum Endpoints

List IBM Quantum Backends

Execute on IBM Quantum

Get IBM Quantum Job Status

Estimate IBM Quantum Cost

AWS Braket Endpoints

List Braket Devices

Execute on AWS Braket

Get Braket Task Status

Estimate Braket Cost

Legacy Execute Endpoint (LUMI)

Legacy Execute Endpoint (LUMI)

Get Job Status (Legacy)

Health & Status

API Health Check

Supplier Status

Error Responses

HTTP Status Codes

Error Codes

Rate Limits

Interactive Documentation

SDKs & Libraries

Python SDK Example

Provider Comparison

Cost Optimization Tips

Migration from v1.x

Support