Everything runs through one canonical API: /api/v1/runtime/*. This guide shows the full loop — list backends → estimate → submit → get results — and the four ways to drive it (API, Python SDK, desktop, shell).

Base URL: your instance (e.g. https://api.softquantus.com, or http://localhost:8377 for the local demo). All examples use $QCOS for the base URL and $KEY for your API key.

Authentication

Every call carries your API key, as a bearer token or X-API-Key:

export QCOS=http://localhost:8377
export KEY=sq-...            # your API key
curl -H "Authorization: Bearer $KEY" "$QCOS/api/v1/runtime/backends"

Read endpoints need the qcos:read scope; submitting jobs needs qcos:execute. On the local demo, auth is disabled (QCOS_AUTH_REQUIRED=false).

1. List backends

curl -H "Authorization: Bearer $KEY" "$QCOS/api/v1/runtime/backends"

Returns { "backends": [...], "total": N }. Each backend:

{
  "id": "ibm_brisbane",
  "provider_source": "ibm_quantum",
  "type": "real_qpu",          // simulator | gpu_simulator | hpc_simulator | real_qpu | other
  "max_qubits": 127,
  "available": true,           // true only when its credentials are configured
  "cost_model": "qsh",
  "supports_byo": true,        // can attach your own credentials (azure/ibm/braket only)
  "supports_qec": true,
  "max_qec_distance": 11,
  "display_name": "IBM Brisbane"
}

Filter with ?backend_type=simulator, ?provider_source=ibm_quantum, or ?available_only=true. A backend is available only when its required environment variables are set — see Add a Quantum Computer.

2. Estimate cost

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  "$QCOS/api/v1/runtime/estimate" \
  -d '{"backend_id":"auto_sim","shots":1024,"qubits":2}'

{
  "backend_id": "auto_sim", "shots": 1024,
  "estimated_cost_usd": 0.0, "credits_required": 0,
  "estimated_duration_ms": 5000, "queue_time_ms": 1000,
  "approval_required": false,
  "warnings": [], "recommendations": []
}

approval_required is true for real QPUs, for estimates ≥ $1.00, or when QEC is enabled.

3. Submit a job

Minimum body: backend_id + a circuit (qasm, OpenQASM 2.0) + shots.

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  "$QCOS/api/v1/runtime/jobs" \
  -d '{
    "backend_id": "auto_sim",
    "shots": 1024,
    "confirm_cost": true,
    "qasm": "OPENQASM 2.0;\ninclude \"qelib1.inc\";\nqreg q[2];\ncreg c[2];\nh q[0];\ncx q[0],q[1];\nmeasure q -> c;"
  }'

Response (202 Accepted):

{
  "job_id": "job_0f1e2d...",
  "status": "completed",
  "backend_id": "auto_sim",
  "result": {
    "backend_id": "auto_sim",
    "provider_source": "statevector_sim",
    "counts": {"00": 511, "11": 513},
    "qubits": 2,
    "shots": 1024,
    "simulated": true,
    "execution_mode": "qcos_simulator",   // or "real_qpu"
    "is_real_qpu": false,
    "execution_time_ms": 12.4
  }
}

Useful request fields:

Field	Meaning
`confirm_cost: true`	Skip the approval gate for a priced job.
`max_cost_usd: 5.0`	Reject (400) if the estimate exceeds this.
`qec_config`	`{enabled, code_type, code_distance, qec_rounds}` — run with QEC.
`session_id`	Attach to an open session/batch.
`metadata.qpu_reservation_id`	Required to run a real QPU (payment proof).

Job states progress: dry_run → approval_required → approved → queued → running → completed | failed | cancelled. Add ?dry_run=true to validate without executing, or POST to /jobs/async to queue.

4. Get results & manage jobs

curl -H "Authorization: Bearer $KEY" "$QCOS/api/v1/runtime/jobs/$JOB_ID"

Other job routes: GET /jobs (list), POST /jobs/{id}/approve?approval_token=…, DELETE /jobs/{id} (cancel), GET /jobs/{id}/events?stream=true (live SSE), GET /jobs/{id}/artifacts.

Running on a REAL quantum computer

Real-QPU backends (type: "real_qpu", including any on-premise device) are gated in three layers — all must pass:

Kill-switch: the operator must set QCOS_REAL_QPU_ENABLED=true, else the door returns 403 real_qpu_disabled.
Payment proof: the job metadata must include one of qpu_reservation_id, qpu_wallet_reservation_id, payment_confirmed:true, or qpu_payment_confirmed:true, else 402 qpu_payment_required.
Plan tier: your account tier must be one of pro, lab, quantum, quantum_ai, enterprise, qpu_starter, qpu_pro, qpu_max, else 403 plan_qpu_access_required.

Without payment proof the job parks in approval_required rather than executing. Simulators have none of these gates and cost 0 credits.

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  "$QCOS/api/v1/runtime/jobs" \
  -d '{"backend_id":"ibm_brisbane","shots":1024,"confirm_cost":true,
       "metadata":{"qpu_reservation_id":"res_abc123"},
       "qasm":"OPENQASM 2.0;\ninclude \"qelib1.inc\";\nqreg q[2];\ncreg c[2];\nh q[0];\ncx q[0],q[1];\nmeasure q -> c;"}'

Ways to drive QCOS

Python / TypeScript SDK

pip install softqcos            # Python product SDK
npm install @softquantus/softqcos-sdk   # TypeScript

The SDK wraps the same runtime API (client.coreJobs.submitJob({...}) in TS). Point it at your instance with your API key.

The desktop app

The QCOS Desktop (browser or the Electron app in packaging/desktop) gives you Device Manager, a Quantum Jobs panel (submit Bell/GHZ/custom QASM, see live counts), live ACOS certification, and a real shell — all over this same API. Run the local demo:

.venv/bin/python -m uvicorn --app-dir "$PWD" examples.oem_console.server:app --port 8377
# open http://localhost:8377/demo

The shell (`sq-status`, container)

On a SoftQuantus Compute OS host (or docker run -it softquantus/compute-os:demo) the branded shell exposes the appliance identity via sq-status and the QCOS control plane runs as a service.

Connect your own QPU → Add a Quantum Computer
Use GPU acceleration → Add a GPU / Simulator
Every setting → Configuration

User Manual

Using QCOS: run quantum circuits end to end

Authentication

1. List backends

2. Estimate cost

3. Submit a job

4. Get results & manage jobs

Running on a REAL quantum computer

Ways to drive QCOS

Python / TypeScript SDK

The desktop app

The shell (`sq-status`, container)

Next

​Authentication

​1. List backends

​2. Estimate cost

​3. Submit a job

​4. Get results & manage jobs

​Running on a REAL quantum computer

​Ways to drive QCOS

​Python / TypeScript SDK

​The desktop app

​The shell (sq-status, container)

​Next

Authentication

1. List backends

2. Estimate cost

3. Submit a job

4. Get results & manage jobs

Running on a REAL quantum computer

Ways to drive QCOS

Python / TypeScript SDK

The desktop app

The shell (`sq-status`, container)

Next