QCOS Core API Endpoints

Optimization

POST /api/v2/optimize

Submit a circuit for quantum optimization.

Request:

{
  "qasm": "OPENQASM 2.0;\ninclude \"qelib1.inc\";\nqreg q[2];\nh q[0];\ncx q[0],q[1];",
  "backend": "ionq_simulator",
  "shots": 1024,
  "options": {
    "optimization_level": 2,
    "evidence": true,
    "pqc_signing": true
  }
}

Parameter	Type	Required	Description
qasm	string	✓	OpenQASM circuit
backend	string	✓	Target backend ID
shots	integer	-	Number of shots (default: 1024)
options.optimization_level	integer	-	0-3 (default: 2)
options.evidence	boolean	-	Generate evidence bundle
options.pqc_signing	boolean	-	Use PQC signatures

Response:

{
  "success": true,
  "data": {
    "job_id": "job_xyz789",
    "status": "queued",
    "estimated_time": 30
  }
}

---

GET /api/v2/optimize/{job_id}

Get optimization job status and results.

Response:

{
  "success": true,
  "data": {
    "job_id": "job_xyz789",
    "status": "completed",
    "original_depth": 45,
    "optimized_depth": 28,
    "reduction_percent": 37.8,
    "results": {
      "counts": {"00": 512, "11": 512},
      "probabilities": {"00": 0.5, "11": 0.5}
    },
    "evidence_bundle_id": "ev_abc123"
  }
}

---

POST /api/v2/optimize/batch

Submit multiple circuits for batch optimization.

Request:

{
  "circuits": [
    {"qasm": "...", "backend": "ionq_simulator"},
    {"qasm": "...", "backend": "ionq_simulator"}
  ],
  "options": {
    "optimization_level": 2
  }
}

Response:

{
  "success": true,
  "data": {
    "batch_id": "batch_abc123",
    "job_ids": ["job_1", "job_2"],
    "status": "processing"
  }
}

---

GET /api/v2/optimize/stats

Get optimization statistics for your account.

Response:

{
  "success": true,
  "data": {
    "total_jobs": 1523,
    "total_circuits": 4891,
    "avg_reduction": 34.7,
    "evaluations_used": 45230,
    "evaluations_limit": 50000
  }
}

---

Backends

GET /api/v2/backends

List available quantum backends.

Response:

{
  "success": true,
  "data": {
    "backends": [
      {
        "id": "ionq_simulator",
        "name": "IonQ Simulator",
        "type": "simulator",
        "qubits": 29,
        "status": "online",
        "queue_depth": 5
      },
      {
        "id": "ionq_aria",
        "name": "IonQ Aria",
        "type": "hardware",
        "qubits": 25,
        "status": "online",
        "queue_depth": 12
      }
    ]
  }
}

---

GET /api/v2/backends/{backend_id}

Get backend details.

Response:

{
  "success": true,
  "data": {
    "id": "ionq_aria",
    "name": "IonQ Aria",
    "type": "hardware",
    "qubits": 25,
    "native_gates": ["GPI", "GPI2", "MS"],
    "connectivity": "all-to-all",
    "average_fidelity": 0.997,
    "status": "online",
    "queue_depth": 12
  }
}

---

GET /api/v2/backends/{backend_id}/calibration

Get current calibration data.

Response:

{
  "success": true,
  "data": {
    "backend_id": "ionq_aria",
    "timestamp": "2026-02-06T10:00:00Z",
    "single_qubit_fidelity": 0.9995,
    "two_qubit_fidelity": 0.997,
    "readout_fidelity": 0.998
  }
}

---

Jobs

GET /api/v2/jobs

List your jobs.

Query Parameters:

Parameter	Type	Description
status	string	Filter by status
limit	integer	Max results (default: 20)
offset	integer	Pagination offset

Response:

{
  "success": true,
  "data": {
    "jobs": [
      {
        "job_id": "job_xyz789",
        "status": "completed",
        "created_at": "2026-02-06T12:00:00Z",
        "completed_at": "2026-02-06T12:00:30Z"
      }
    ],
    "pagination": {
      "total": 150,
      "limit": 20,
      "offset": 0
    }
  }
}

---

GET /api/v2/jobs/{job_id}

Get job details.

---

DELETE /api/v2/jobs/{job_id}

Cancel a pending job.

Response:

{
  "success": true,
  "data": {
    "job_id": "job_xyz789",
    "status": "cancelled"
  }
}

---

POST /api/v2/jobs/{job_id}/retry

Retry a failed job.

---

Evidence

GET /api/v2/evidence/{bundle_id}

Get evidence bundle.

Response:

{
  "success": true,
  "data": {
    "bundle_id": "ev_abc123",
    "version": "3.0",
    "created_at": "2026-02-06T12:00:00Z",
    "circuit_hash": "sha3-256:abc123...",
    "execution_proof": {
      "backend": "ionq_simulator",
      "shots": 1024,
      "timestamp": "2026-02-06T12:00:15Z"
    },
    "signatures": {
      "algorithm": "ML-DSA-65",
      "signature": "base64:..."
    }
  }
}

---

POST /api/v2/evidence/verify

Verify an evidence bundle.

Request:

{
  "bundle": { ... }
}

Response:

{
  "success": true,
  "data": {
    "valid": true,
    "checks": {
      "signature": "valid",
      "hash": "valid",
      "timestamp": "valid"
    }
  }
}

---

GET /api/v2/evidence/export/{bundle_id}

Export evidence bundle in various formats.

Query Parameters:

Parameter	Values
format	json, pdf, cbor

---

Health

GET /health

Basic health check.

{
  "status": "ok"
}

---

GET /api/v2/status

Detailed system status.

{
  "success": true,
  "data": {
    "api": "operational",
    "backends": {
      "ionq_simulator": "online",
      "ionq_aria": "online"
    },
    "queue_depth": 17,
    "avg_response_time_ms": 45
  }
}

---

Error Codes

Code	HTTP	Description
INVALID_CIRCUIT	400	Circuit validation failed
BACKEND_UNAVAILABLE	503	Backend offline
RATE_LIMIT_EXCEEDED	429	Rate limit hit
UNAUTHORIZED	401	Invalid API key
QUOTA_EXCEEDED	403	Evaluation quota exceeded
JOB_NOT_FOUND	404	Job ID not found
INTERNAL_ERROR	500	Server error

---

© 2024-2026 SoftQuantus Innovative OÜ