API Reference

Complete REST API reference for QCOS.

Base URL

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

Endpoints

Health Check

GET /

Check API health status.

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "queue_connected": true
}

---

Execute Circuit

POST /execute

Submit a quantum circuit for execution.

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"
}

Field	Type	Required	Description
qasm	string	Yes	OpenQASM 2.0 circuit
shots	integer	No	Number of shots (default: 1024)
job_id	string	No	Custom job identifier

Response:

{
  "job_id": "abc123-def456-ghi789",
  "status": "queued",
  "message": "Job queued for GPU execution on LUMI",
  "estimated_time_seconds": 30
}

Example:

curl -X POST https://api.softquantus.com/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "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
  }'

---

Get Job Status

GET /status/{job_id}

Get the status of a submitted job.

Path Parameters:

Parameter	Type	Description
job_id	string	Job identifier

Response:

{
  "job_id": "abc123-def456-ghi789",
  "status": "completed",
  "result": {
    "counts": {"00": 512, "11": 512},
    "num_qubits": 2,
    "shots": 1024,
    "execution_time_seconds": 0.05,
    "backend": "cuStateVec",
    "device": "NVIDIA A100"
  },
  "error": null,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:02Z"
}

Status Values:

Status	Description
queued	Job is waiting in queue
processing	Job is being executed
completed	Job finished successfully
failed	Job failed with error

---

Get Job Results

GET /results/{job_id}

Get results with optional wait.

Query Parameters:

Parameter	Type	Default	Description
wait	boolean	false	Wait for completion
timeout	integer	30	Max seconds to wait

Response (completed):

{
  "job_id": "abc123-def456-ghi789",
  "status": "completed",
  "result": {
    "counts": {"00": 512, "11": 512}
  }
}

Response (pending):

{
  "job_id": "abc123-def456-ghi789",
  "status": "pending",
  "message": "Job not yet completed"
}

---

User Information

GET /user/me

Get current user information.

Response:

{
  "user_id": "user_abc123",
  "email": "demo@example.com",
  "tier": "pro",
  "daily_job_limit": 100,
  "max_qubits": 50,
  "max_shots": 100000,
  "jobs_today": 23,
  "jobs_total": 456
}

---

User Usage

GET /user/usage

Get usage statistics.

Response:

{
  "user_id": "user_abc123",
  "period": "2024-01",
  "jobs_executed": 234,
  "total_shots": 1234567,
  "total_qubits_hours": 45.6,
  "daily_usage": [
    {"date": "2024-01-15", "jobs": 12},
    {"date": "2024-01-14", "jobs": 8}
  ]
}

---

Pricing Information

GET /pricing

Get pricing tiers (no auth required).

Response:

{
  "tiers": [
    {
      "name": "free",
      "price_monthly": 0,
      "daily_job_limit": 10,
      "max_qubits": 20,
      "max_shots": 10000
    },
    {
      "name": "pro",
      "price_monthly": 49,
      "daily_job_limit": 100,
      "max_qubits": 50,
      "max_shots": 100000
    },
    {
      "name": "enterprise",
      "price_monthly": null,
      "daily_job_limit": -1,
      "max_qubits": 100,
      "max_shots": 1000000
    }
  ]
}

---

Error Responses

All errors follow this format:

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

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Rate Limited
500	Server Error
503	Service Unavailable

Error Codes

Code	Description
AUTH_REQUIRED	No API key provided
AUTH_INVALID	Invalid API key
RATE_LIMITED	Too many requests
QUOTA_EXCEEDED	Tier limit exceeded
CIRCUIT_INVALID	Invalid circuit syntax
JOB_NOT_FOUND	Job ID not found
JOB_FAILED	Execution failed

---

Rate Limits

Tier	Requests/Minute	Requests/Day
Free	10	100
Pro	60	1000
Enterprise	300	Unlimited

Rate limit headers:

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

---

OpenAPI Specification

Interactive API documentation available at:

• Swagger UI: https://api.softquantus.com/docs
• ReDoc: https://api.softquantus.com/redoc
• OpenAPI JSON: https://api.softquantus.com/openapi.json

---

SDKs & Libraries

Language	Package	Install
Python	qcos-sdk	pip install qcos-sdk
JavaScript	@softquantus/qcos	npm install @softquantus/qcos
Rust	qcos	cargo add qcos
Go	qcos-go	go get github.com/softquantus/qcos-go