Migration Guide: v1.x → v2.x
This guide covers all breaking changes between QCOS v1.x and v2.x with code examples.
1. Package Names
| Component | v1.x | v2.x |
|---|---|---|
| SDK | pip install qcos-sdk | pip install softqcos-sdk |
| CLI | pip install qcos-cli | pip install softqcos |
| CLI binary | qcos | softqcos |
2. Base URL
- https://api.softquantus.com/api/v1/
+ https://api.softquantus.com/api/v2/
3. Authentication Header
# REST API
- X-API-Key: qcos_abc123
+ Authorization: Bearer qcos_abc123
The SDK handles this automatically. For direct REST calls, update your headers.
4. SDK Client Initialization
- from qcos import QCOSClient
- client = QCOSClient(token="qcos_abc123")
+ from softqcos_sdk import QCOSClient
+ client = QCOSClient(api_key="qcos_abc123")
Environment variable:
- export QCOS_TOKEN=qcos_abc123
+ export QCOS_API_KEY=qcos_abc123
5. SDK Method Renames
Jobs
- client.jobs.submit_job(qasm, shots=1024)
+ client.jobs.submit(qasm, shots=1024)
- client.jobs.get_job(job_id)
+ client.jobs.get(job_id)
- client.jobs.get_results(job_id)
+ client.jobs.results(job_id)
- client.jobs.list_jobs()
+ client.jobs.list()
- client.jobs.cancel_job(job_id)
+ client.jobs.cancel(job_id)
Backends
- client.backends.get_backends()
+ client.backends.list()
- client.backends.get_backend(backend_id)
+ client.backends.get(backend_id)
- client.backends.add_backend(**kwargs)
+ client.backends.add(**kwargs)
- client.backends.delete_backend(backend_id)
+ client.backends.delete(backend_id)
Circuits
- client.circuits.validate_circuit(qasm)
+ client.circuits.validate(qasm)
- client.circuits.optimize_circuit(qasm)
+ client.circuits.optimize(qasm)
Bench
- client.bench.run_benchmark(backend)
+ client.bench.run(backend)
- client.bench.get_report(benchmark_id)
+ client.bench.report(benchmark_id)
6. Response Format
v1.x (flat)
{
"job_id": "abc123",
"status": "COMPLETED",
"counts": {"00": 512, "11": 512}
}
v2.x (nested with metadata)
{
"data": {
"job_id": "abc123",
"status": "COMPLETED",
"counts": {"00": 512, "11": 512}
},
"meta": {
"request_id": "req_xyz789",
"timestamp": "2024-11-01T12:00:00Z",
"version": "2.0"
}
}
note
The SDK automatically unwraps the data field, so client.jobs.get(job_id) returns the inner object directly. This change only affects direct REST API calls.
7. Error Format
v1.x
{
"error": "Job not found"
}
v2.x
{
"error": {
"code": "JOB_NOT_FOUND",
"detail": "Job abc123 not found",
"status": 404,
"request_id": "req_xyz789"
}
}
SDK exceptions now include .code, .detail, and .request_id attributes:
from softqcos_sdk.exceptions import JobNotFoundError
try:
client.jobs.get("nonexistent")
except JobNotFoundError as e:
print(e.code) # "JOB_NOT_FOUND"
print(e.detail) # "Job nonexistent not found"
print(e.status_code) # 404
8. CLI Command Changes
# Command prefix
- qcos jobs list
+ softqcos jobs list
# Output format flag
- qcos jobs list --format json
+ softqcos jobs list -o json
# Submit shorthand
- qcos run circuit.qasm --shots 1024
+ softqcos jobs run circuit.qasm --shots 1024
# Config
- qcos config set token "qcos_abc123"
+ softqcos config set api_key "qcos_abc123"
9. New Features in v2.x
These are additive — no migration needed:
| Feature | API | Description |
|---|---|---|
| QuantumNet™ | client.network | Multi-QPU networking |
| QEC Runtime™ | client.qec | Error correction |
| ZoneGuard™ | client.isolation | Qubit isolation |
| QuantumLedger™ | client.ledger | Metering & governance |
| ACOS-ISA™ | client.acos | Certification |
| Quantum Macro™ | client.macro | Strategic analysis |
| Evidence Portal | client.evidence | Evidence downloads |
| DRI | client.dri | Device readiness |
| NavCore™ (v2.1) | client.navcore | Quantum navigation |
| Async Client (v2.1) | AsyncQCOSClient | Concurrent operations |
10. Quick Migration Script
For Python codebases, find and replace:
# Package import
find . -name "*.py" -exec sed -i '' 's/from qcos import/from softqcos_sdk import/g' {} +
# Client init
find . -name "*.py" -exec sed -i '' 's/QCOSClient(token=/QCOSClient(api_key=/g' {} +
# Method renames
find . -name "*.py" -exec sed -i '' \
-e 's/\.submit_job(/\.submit(/g' \
-e 's/\.get_job(/\.get(/g' \
-e 's/\.get_results(/\.results(/g' \
-e 's/\.list_jobs(/\.list(/g' \
-e 's/\.cancel_job(/\.cancel(/g' \
-e 's/\.get_backends(/\.list(/g' \
-e 's/\.get_backend(/\.get(/g' \
-e 's/\.validate_circuit(/\.validate(/g' \
-e 's/\.optimize_circuit(/\.optimize(/g' \
-e 's/\.run_benchmark(/\.run(/g' \
-e 's/\.get_report(/\.report(/g' \
{} +
# Environment variable
# Update .env files
sed -i '' 's/QCOS_TOKEN/QCOS_API_KEY/g' .env*
Need Help?
- Getting Started — Fresh start with v2.x
- SDK Reference — Complete method reference
- Changelog — Full release history