QCOS API Reference

Complete REST API documentation for the Quantum Circuit Optimization Service.

Base URL

https://api.softqcos.softquantus.com/v2

Authentication

All API requests require authentication via the X-API-Key header:

curl -H "X-API-Key: your-api-key" \
     https://api.softqcos.softquantus.com/v2/circuits

Rate Limits

Plan	Requests/min	Requests/day
Free	60	1,000
Pro	300	10,000
Hybrid	600	50,000
Enterprise	Custom	Custom

Circuits

Submit Circuit

Submit a quantum circuit for execution.

POST /v2/circuits

Request Body:

{
  "circuit": {
    "qasm": "OPENQASM 2.0; ...",
    "format": "qasm2"
  },
  "backend": "ibm_brisbane",
  "shots": 1000,
  "optimization_level": 2,
  "options": {
    "memory": true,
    "seed_simulator": 42
  }
}

Field	Type	Required	Description
`circuit`	object	Yes	Circuit definition
`circuit.qasm`	string	Yes*	OpenQASM string
`circuit.qiskit_json`	string	Yes*	Qiskit JSON export
`circuit.format`	string	Yes	`qasm2`, `qasm3`, or `qiskit`
`backend`	string	Yes	Target backend ID
`shots`	integer	No	Number of shots (default: 1000)
`optimization_level`	integer	No	0-3 (default: 2)
`options.memory`	boolean	No	Return per-shot results
`options.seed_simulator`	integer	No	Simulator seed

Response:

{
  "job_id": "qcos_job_abc123",
  "status": "queued",
  "backend": "ibm_brisbane",
  "created_at": "2024-01-15T10:30:00Z",
  "estimated_wait": 120,
  "optimization": {
    "original_depth": 45,
    "optimized_depth": 28,
    "reduction_percent": 37.8
  }
}

Get Job Status

Check the status of a submitted job.

GET /v2/jobs/{job_id}

Response:

{
  "job_id": "qcos_job_abc123",
  "status": "completed",
  "backend": "ibm_brisbane",
  "created_at": "2024-01-15T10:30:00Z",
  "started_at": "2024-01-15T10:32:00Z",
  "completed_at": "2024-01-15T10:32:15Z",
  "execution_time_ms": 15000,
  "quantum_minutes": 0.25,
  "shots": 1000
}

Status Values:

Status	Description
`queued`	Waiting in queue
`validating`	Circuit validation in progress
`optimizing`	Optimization in progress
`running`	Executing on quantum hardware
`completed`	Successfully completed
`failed`	Execution failed
`cancelled`	Cancelled by user

Get Job Results

Retrieve results of a completed job.

GET /v2/jobs/{job_id}/results

Response:

{
  "job_id": "qcos_job_abc123",
  "counts": {
    "00": 498,
    "11": 502
  },
  "memory": ["00", "11", "00", "11", "..."],
  "metadata": {
    "backend": "ibm_brisbane",
    "shots": 1000,
    "execution_time_ms": 15000,
    "optimization_level": 2
  },
  "quality_metrics": {
    "success_probability": 0.95,
    "fidelity_estimate": 0.89
  }
}

Cancel Job

Cancel a queued or running job.

DELETE /v2/jobs/{job_id}

Response:

{
  "job_id": "qcos_job_abc123",
  "status": "cancelled",
  "refunded_minutes": 0.0
}

List Jobs

List all jobs for your account.

GET /v2/jobs

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status
`backend`	string	Filter by backend
`limit`	integer	Max results (default: 50)
`offset`	integer	Pagination offset
`from`	datetime	Start date (ISO 8601)
`to`	datetime	End date (ISO 8601)

Example:

curl -H "X-API-Key: your-api-key" \
     "https://api.softqcos.softquantus.com/v2/jobs?status=completed&limit=10"

Backends

List Backends

Get all available quantum backends.

GET /v2/backends

Response:

{
  "backends": [
    {
      "id": "ibm_brisbane",
      "provider": "ibm",
      "name": "IBM Brisbane",
      "qubits": 127,
      "status": "online",
      "queue_length": 15,
      "average_wait_minutes": 5,
      "features": ["dynamic_circuits", "mid_circuit_measurement"],
      "pricing": {
        "rate_per_minute": 115.20,
        "currency": "USD"
      }
    },
    {
      "id": "ionq_aria",
      "provider": "aws",
      "name": "IonQ Aria",
      "qubits": 25,
      "status": "online",
      "queue_length": 3,
      "average_wait_minutes": 2,
      "pricing": {
        "rate_per_shot": 0.036,
        "task_fee": 0.36,
        "currency": "USD"
      }
    }
  ]
}

Get Backend Details

Get detailed information about a specific backend.

GET /v2/backends/{backend_id}

Response:

{
  "id": "ibm_brisbane",
  "provider": "ibm",
  "name": "IBM Brisbane",
  "processor": "Eagle r3",
  "qubits": 127,
  "status": "online",
  "connectivity": "heavy_hex",
  "basis_gates": ["cx", "id", "rz", "sx", "x"],
  "max_shots": 100000,
  "max_circuits": 300,
  "calibration": {
    "last_updated": "2024-01-15T08:00:00Z",
    "t1_us": 264.5,
    "t2_us": 127.8,
    "readout_error": 0.012,
    "cx_error": 0.008
  },
  "maintenance": {
    "next_scheduled": "2024-01-20T02:00:00Z",
    "duration_hours": 4
  }
}

Optimization

Optimize Circuit

Optimize a circuit without execution.

POST /v2/optimize

Request Body:

{
  "circuit": {
    "qasm": "OPENQASM 2.0; ...",
    "format": "qasm2"
  },
  "target_backend": "ibm_brisbane",
  "optimization_level": 3,
  "preserve_layout": false
}

Response:

{
  "optimized_circuit": {
    "qasm": "OPENQASM 2.0; ...",
    "format": "qasm2"
  },
  "metrics": {
    "original_depth": 120,
    "optimized_depth": 72,
    "original_gates": 450,
    "optimized_gates": 285,
    "depth_reduction_percent": 40.0,
    "gate_reduction_percent": 36.7
  },
  "qubit_mapping": {
    "0": 12,
    "1": 15,
    "2": 18
  },
  "credits_used": 2
}

Simulation

Run Simulation

Execute circuit on HPC simulator.

POST /v2/simulate

Request Body:

{
  "circuit": {
    "qasm": "OPENQASM 2.0; ...",
    "format": "qasm2"
  },
  "shots": 10000,
  "noise_model": "ibm_brisbane",
  "method": "statevector"
}

Field	Type	Description
`noise_model`	string	Backend to emulate (optional)
`method`	string	`statevector`, `density_matrix`, or `mps`

Response:

{
  "simulation_id": "sim_xyz789",
  "counts": {
    "00": 4980,
    "11": 5020
  },
  "statevector": [0.707, 0, 0, 0.707],
  "execution_time_ms": 245,
  "simulation_minutes": 0.1,
  "method": "statevector"
}

Account

Get Usage

Get current billing period usage.

GET /v2/account/usage

Response:

{
  "billing_period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "plan": "pro",
  "quantum_minutes": {
    "used": 45.5,
    "included": 60,
    "overage": 0
  },
  "simulation_minutes": {
    "used": 230,
    "included": 500
  },
  "optimization_credits": {
    "used": 150,
    "included": 1000
  },
  "api_calls": {
    "used": 5420,
    "limit": 10000
  },
  "estimated_bill": 99.00
}

Get Quotas

Get account quotas and limits.

GET /v2/account/quotas

Response:

{
  "plan": "pro",
  "quotas": {
    "quantum_minutes_monthly": 60,
    "simulation_minutes_monthly": 500,
    "optimization_credits_monthly": 1000,
    "max_qubits": 127,
    "max_circuit_depth": 1000,
    "max_shots": 100000,
    "concurrent_jobs": 5
  },
  "features": {
    "multi_backend": true,
    "synapsex_integration": "basic",
    "custom_noise_models": false,
    "priority_queue": false
  }
}

Errors

Error Response Format

{
  "error": {
    "code": "INVALID_CIRCUIT",
    "message": "Circuit contains invalid gate 'xyz'",
    "details": {
      "line": 15,
      "gate": "xyz"
    }
  },
  "request_id": "req_abc123"
}

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`INVALID_CIRCUIT`	400	Circuit validation failed
`INVALID_BACKEND`	400	Backend not found or unavailable
`QUOTA_EXCEEDED`	429	Usage quota exceeded
`RATE_LIMITED`	429	Too many requests
`BACKEND_ERROR`	502	Quantum backend error
`INTERNAL_ERROR`	500	Internal server error

Webhooks

Configure Webhook

Receive notifications when jobs complete.

POST /v2/webhooks

Request Body:

{
  "url": "https://your-server.com/webhook",
  "events": ["job.completed", "job.failed"],
  "secret": "your-webhook-secret"
}

Webhook Payload:

{
  "event": "job.completed",
  "timestamp": "2024-01-15T10:32:15Z",
  "data": {
    "job_id": "qcos_job_abc123",
    "status": "completed",
    "backend": "ibm_brisbane"
  },
  "signature": "sha256=..."
}

SDKs & Libraries

Official SDKs wrap this API for convenience:

Python: pip install softqcos-sdk - SDK Reference
JavaScript: npm install @softquantus/softqcos (coming soon)
Rust: cargo add softqcos (coming soon)

Changelog

v2.1.0 (2024-01)

Added SynapseX integration endpoints
New optimization metrics in response
Webhook support

v2.0.0 (2023-10)

Complete API redesign
Multi-backend support
New authentication system

See full changelog for details.

Base URL​

Authentication​

Rate Limits​

Circuits​

Submit Circuit​

Get Job Status​

Get Job Results​

Cancel Job​

List Jobs​

Backends​

List Backends​

Get Backend Details​

Optimization​

Optimize Circuit​

Simulation​

Run Simulation​

Account​

Get Usage​

Get Quotas​

Errors​

Error Response Format​

Error Codes​

Webhooks​

Configure Webhook​

SDKs & Libraries​

Changelog​

v2.1.0 (2024-01)​

v2.0.0 (2023-10)​

Base URL

Authentication

Rate Limits

Circuits

Submit Circuit

Get Job Status

Get Job Results

Cancel Job

List Jobs

Backends

List Backends

Get Backend Details

Optimization

Optimize Circuit

Simulation

Run Simulation

Account

Get Usage

Get Quotas

Errors

Error Response Format

Error Codes

Webhooks

Configure Webhook

SDKs & Libraries

Changelog

v2.1.0 (2024-01)

v2.0.0 (2023-10)