API Capabilities

Complete reference of all REST API endpoints available in the QCOS API Gateway.

Base URLs

Environment	URL
Production	`https://api.softquantus.com`
Internal	`https://sqt-prod-softqcos-server-ca.icybay-7dfb32ea.westeurope.azurecontainerapps.io`

Authentication

All endpoints require authentication via API key:

# Header method (recommended)
curl -H "X-API-Key: your-api-key" https://api.softquantus.com/api/v1/execute

# Bearer token method
curl -H "Authorization: Bearer your-api-key" https://api.softquantus.com/api/v1/execute

Health & Status Endpoints

GET /

Health check with detailed status.

curl https://api.softquantus.com/

Response:

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

GET /health

Simple health check for load balancers.

curl https://api.softquantus.com/health

Response:

{
  "status": "ok"
}

GET /ready

Readiness check for Kubernetes.

curl https://api.softquantus.com/ready

Circuit Execution

POST /api/v1/execute

Execute a quantum circuit asynchronously.

curl -X POST https://api.softquantus.com/api/v1/execute \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "qasm": "OPENQASM 2.0;\ninclude \"qelib1.inc\";\nqreg q[2];\ncreg c[2];\nh q[0];\ncx q[0],q[1];\nmeasure q -> c;",
    "shots": 1024
  }'

Request Body:

Field	Type	Required	Description
`qasm`	string	✅	OpenQASM 2.0 circuit
`shots`	int		Number of shots (1-100000, default: 1024)
`job_id`	string		Custom job ID

Response:

{
  "job_id": "job_abc123xyz",
  "status": "queued",
  "message": "Job queued for processing",
  "estimated_time_seconds": 30
}

GET /api/v1/status/{job_id}

Get job status.

curl https://api.softquantus.com/api/v1/status/job_abc123xyz \
  -H "X-API-Key: your-api-key"

Response:

{
  "job_id": "job_abc123xyz",
  "status": "completed",
  "result": {
    "counts": {"00": 512, "11": 512}
  },
  "created_at": "2026-01-03T12:00:00Z",
  "completed_at": "2026-01-03T12:00:15Z"
}

Status Values:

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

GET /api/v1/results/{job_id}

Get job results.

curl https://api.softquantus.com/api/v1/results/job_abc123xyz \
  -H "X-API-Key: your-api-key"

Response:

{
  "job_id": "job_abc123xyz",
  "counts": {"00": 512, "11": 512},
  "metadata": {
    "shots": 1024,
    "backend": "qiskit_aer",
    "execution_time_ms": 150
  }
}

DELETE /api/v1/jobs/{job_id}

Cancel a queued job.

curl -X DELETE https://api.softquantus.com/api/v1/jobs/job_abc123xyz \
  -H "X-API-Key: your-api-key"

POST /execute-sync

Execute a circuit synchronously (blocks until completion).

curl -X POST https://api.softquantus.com/execute-sync \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"qasm": "...", "shots": 1024}'

Response: Direct result without needing to poll status.

Multi-Supplier Endpoints

GET /api/v1/suppliers

List all available quantum suppliers.

curl https://api.softquantus.com/api/v1/suppliers \
  -H "X-API-Key: your-api-key"

Response:

{
  "suppliers": [
    {
      "id": "azure_quantum",
      "name": "Azure Quantum",
      "status": "active",
      "providers_count": 4
    },
    {
      "id": "ibm_quantum",
      "name": "IBM Quantum",
      "status": "active",
      "providers_count": 4
    },
    {
      "id": "braket",
      "name": "AWS Braket",
      "status": "active",
      "providers_count": 6
    }
  ]
}

GET /api/v1/{supplier}/providers

List providers for a specific supplier.

# Azure Quantum
curl https://api.softquantus.com/api/v1/azure_quantum/providers \
  -H "X-API-Key: your-api-key"

# IBM Quantum
curl https://api.softquantus.com/api/v1/ibm_quantum/providers \
  -H "X-API-Key: your-api-key"

# AWS Braket
curl https://api.softquantus.com/api/v1/braket/providers \
  -H "X-API-Key: your-api-key"

Response:

{
  "providers": [
    {
      "id": "ionq",
      "name": "IonQ",
      "num_qubits": 29,
      "targets": ["ionq.aria", "ionq.harmony", "ionq.simulator"],
      "description": "Trapped-ion quantum computer",
      "cost_model": "per_aqt"
    },
    {
      "id": "quantinuum",
      "name": "Quantinuum",
      "num_qubits": 56,
      "targets": ["quantinuum.h1-1", "quantinuum.h1-2", "quantinuum.h2-1"],
      "description": "Highest fidelity trapped-ion QPU",
      "cost_model": "hqc_credits"
    }
  ]
}

POST /api/v1/{supplier}/execute

Execute on a specific supplier.

curl -X POST https://api.softquantus.com/api/v1/azure_quantum/execute \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "qasm": "...",
    "backend": "ionq.simulator",
    "shots": 1024
  }'

Reranking (Quantum Optimization)

POST /rerank

Submit a reranking job using quantum optimization.

curl -X POST https://api.softquantus.com/rerank \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "candidates": ["text1", "text2", "text3", "text4"],
    "query": "search query",
    "k": 4,
    "tier": "quantum_gpu",
    "max_iters": 50
  }'

Request Body:

Field	Type	Required	Description
`candidates`	array	✅	List of text candidates (2-100)
`query`	string	✅	Query for relevance scoring
`k`	int		Top k results (1-20, default: 4)
`tier`	string		Tier: classic, quantum_cpu, quantum_gpu
`max_iters`	int		Max iterations (10-200, default: 50)

GET /rerank/{job_id}

Get reranking job status and results.

curl https://api.softquantus.com/rerank/job_abc123 \
  -H "X-API-Key: your-api-key"

Response:

{
  "job_id": "job_abc123",
  "status": "completed",
  "tier": "quantum_gpu",
  "ranked_candidates": [
    {"text": "text3", "score": 0.95, "rank": 1},
    {"text": "text1", "score": 0.82, "rank": 2},
    {"text": "text4", "score": 0.71, "rank": 3},
    {"text": "text2", "score": 0.45, "rank": 4}
  ],
  "processing_time_seconds": 2.5
}

User Management

GET /user/me

Get current user information.

curl https://api.softquantus.com/user/me \
  -H "X-API-Key: your-api-key"

Response:

{
  "user_id": "user_abc123",
  "email": "user@example.com",
  "tier": "professional",
  "daily_job_limit": 1000,
  "max_qubits": 50,
  "max_shots": 10000,
  "jobs_today": 42,
  "jobs_total": 1500
}

GET /user/usage

Get usage statistics.

curl https://api.softquantus.com/user/usage \
  -H "X-API-Key: your-api-key"

Admin Endpoints

These endpoints require admin API key.

POST /admin/users

Create a new user.

curl -X POST https://api.softquantus.com/admin/users \
  -H "X-API-Key: admin-api-key" \
  -H "Content-Type: application/json" \
  -d '{"email": "newuser@example.com", "tier": "professional"}'

Response:

{
  "user_id": "user_new123",
  "email": "newuser@example.com",
  "tier": "professional",
  "api_key": "qcos_live_abc123xyz..."
}

warning

The api_key is only shown once. Store it securely.

GET /admin/users/{user_id}

Get user details (admin only).

curl https://api.softquantus.com/admin/users/user_abc123 \
  -H "X-API-Key: admin-api-key"

License Endpoints

GET /api/v1/license/status

Check license status.

curl https://api.softquantus.com/api/v1/license/status \
  -H "X-API-Key: your-api-key"

Response:

{
  "valid": true,
  "type": "enterprise",
  "expires_at": "2026-12-31",
  "features": ["core", "optimization", "multi-supplier", "ledger"],
  "quantum_verified": true
}

Legal Endpoints

GET /legal

Get legal document links.

curl https://api.softquantus.com/legal

Response:

{
  "company": {
    "name": "SoftQuantus innovative OÜ",
    "registry_code": "17048927",
    "address": "Veskiposti tn 2-1002, Tallinn, Estonia",
    "country": "Estonia",
    "eu_member": true
  },
  "documents": {
    "license": "https://softquantus.com/legal/license",
    "eula": "https://softquantus.com/legal/eula",
    "terms": "https://softquantus.com/legal/terms",
    "privacy": "https://softquantus.com/legal/privacy"
  }
}

GET /legal/{document}

Get specific legal document.

curl https://api.softquantus.com/legal/eula

Pricing

GET /pricing

Get pricing tiers and limits.

curl https://api.softquantus.com/pricing

Response:

{
  "tiers": [
    {
      "name": "free",
      "daily_jobs": 10,
      "max_qubits": 20,
      "max_shots": 1024,
      "price_eur": 0
    },
    {
      "name": "professional",
      "daily_jobs": 1000,
      "max_qubits": 50,
      "max_shots": 10000,
      "price_eur": 99
    },
    {
      "name": "enterprise",
      "daily_jobs": "unlimited",
      "max_qubits": 127,
      "max_shots": 100000,
      "price_eur": "custom"
    }
  ]
}

Ledger Endpoints (FinOps)

Enterprise endpoints for financial operations and auditing.

GET /api/v1/ledger/usage

Get usage ledger for billing.

GET /api/v1/ledger/chargeback

Get chargeback reports by tenant/project.

GET /api/v1/ledger/budgets

Get budget allocations and remaining amounts.

POST /api/v1/ledger/evidence

Create evidence bundle for audit.

Error Responses

All errors follow this format:

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

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limited
500	Internal Server Error
503	Service Unavailable

Rate Limits

Tier	Requests/Minute	Daily Jobs
Free	60	10
Professional	300	1,000
Enterprise	1,000	Unlimited

Rate limit headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1704290400

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

Base URLs​

Authentication​

Health & Status Endpoints​

GET /​

GET /health​

GET /ready​

Circuit Execution​

POST /api/v1/execute​

GET /api/v1/status/{job_id}​

GET /api/v1/results/{job_id}​

DELETE /api/v1/jobs/{job_id}​

POST /execute-sync​

Multi-Supplier Endpoints​

GET /api/v1/suppliers​

GET /api/v1/{supplier}/providers​

POST /api/v1/{supplier}/execute​

Reranking (Quantum Optimization)​

POST /rerank​

GET /rerank/{job_id}​

User Management​

GET /user/me​

GET /user/usage​

Admin Endpoints​

POST /admin/users​

GET /admin/users/{user_id}​

License Endpoints​

GET /api/v1/license/status​

Legal Endpoints​

GET /legal​

GET /legal/{document}​

Pricing​

GET /pricing​

Ledger Endpoints (FinOps)​

GET /api/v1/ledger/usage​

GET /api/v1/ledger/chargeback​

GET /api/v1/ledger/budgets​

POST /api/v1/ledger/evidence​

Error Responses​

HTTP Status Codes​

Rate Limits​

OpenAPI Specification​

Base URLs

Authentication

Health & Status Endpoints

GET /

GET /health

GET /ready

Circuit Execution

POST /api/v1/execute

GET /api/v1/status/{job_id}

GET /api/v1/results/{job_id}

DELETE /api/v1/jobs/{job_id}

POST /execute-sync

Multi-Supplier Endpoints

GET /api/v1/suppliers

GET /api/v1/{supplier}/providers

POST /api/v1/{supplier}/execute

Reranking (Quantum Optimization)

POST /rerank

GET /rerank/{job_id}

User Management

GET /user/me

GET /user/usage

Admin Endpoints

POST /admin/users

GET /admin/users/{user_id}

License Endpoints

GET /api/v1/license/status

Legal Endpoints

GET /legal

GET /legal/{document}

Pricing

GET /pricing

Ledger Endpoints (FinOps)

GET /api/v1/ledger/usage

GET /api/v1/ledger/chargeback

GET /api/v1/ledger/budgets

POST /api/v1/ledger/evidence

Error Responses

HTTP Status Codes

Rate Limits

OpenAPI Specification