SoftQuantus Platform REST API reference (/api/v1/platform)

The REST API is the platform’s native contract — any language, any HTTP client, no SDK required. The Python SDK and CLI are thin wrappers over exactly these endpoints.

Base URL: https://platform.softquantus.com
Auth: Authorization: Bearer sq-live-... on every request (create a key under API Keys).
Content type: application/json.

The console itself uses cookie sessions, which additionally require an X-CSRF-Token header on writes. API keys are pure bearer auth — no cookies, no CSRF. Requests are rate limited per IP (default 60/minute; auth endpoints 10/minute) — exceeding it returns 429 with code rate_limit_exceeded.

Endpoints

Execution Plane

Method & path	Purpose
`POST /api/v1/platform/execution/jobs`	Submit a workload (circuit / GPU / CPU). `201` new, `200` idempotent replay
`GET /api/v1/platform/execution/jobs/{id}`	One job’s status and cost
`POST /api/v1/platform/execution/jobs/{id}/cancel`	Cancel; releases unused reservation
`GET /api/v1/platform/execution/jobs/{id}/evidence`	Evidence Bundle once settled (`409` before)
`GET /api/v1/platform/execution/jobs/{id}/usage`	Same job object (usage view)

Usage & billing

Method & path	Purpose
`GET /api/v1/platform/usage/jobs`	Paginated job history (`page`, `page_size`, filter by `backend`, `type=gpu\|qpu\|simulator`)
`GET /api/v1/platform/usage`	Current-month usage report (daily, by backend/provider/type)
`GET /api/v1/platform/usage/ledger`	Immutable per-job credit ledger
`GET /api/v1/platform/billing/summary`	Plan + prepaid balance (`prepaidBalanceUsd`) + limits
`PATCH /api/v1/platform/billing/limits`	Set soft/hard spend limits (owner/admin)
`POST /api/v1/platform/billing/topup-session`	Start a credit top-up (owner/admin, EUR, max €50,000)
`GET /api/v1/platform/billing/invoices`	Recent invoices
`GET /api/v1/platform/billing/plans`	Plan catalog

Quantum instances

Method & path	Purpose
`GET /api/v1/platform/quantum-instances`	List instances
`POST /api/v1/platform/quantum-instances`	Create (plan, `qpus` allowlist, access group)
`DELETE /api/v1/platform/quantum-instances/{id}`	Retire an instance
`GET /api/v1/platform/quantum-instances/paygo/status`	Pay-as-you-go release status
`POST /api/v1/platform/quantum-instances/paygo/request`	Request pay-as-you-go
`GET /api/v1/platform/quantum-instances/pricing-catalog`	Provider-published prices + platform rates

QCOS runtime proxy

Authenticated access to the QCOS runtime without exposing QCOS credentials; the platform injects a runtime key and binds the call to your workspace. Viewers hold qcos:read only; execution requires an execute-capable role.

Method & path	Purpose
`GET /api/v1/platform/qcos/backends`	QPU/simulator devices reachable via QCOS
`GET /api/v1/platform/qcos/jobs`	Your QCOS runtime jobs
`GET /api/v1/platform/qcos/jobs/{id}/execution-evidence`	The QCOS sealed execution-evidence artifact
`POST /api/v1/platform/qcos/estimate`	Price a circuit before running it
`POST /api/v1/platform/qcos/primitives/sampler`	Run a circuit via the Runtime Sampler (`qasm` + `backend_id` required)

Workspace management

Method & path	Purpose
`GET/POST /api/v1/platform/api-keys`, `POST .../{id}/revoke`, `DELETE .../{id}`	API keys
`GET /api/v1/platform/team/members`, `POST /team/invite`, `POST /team/accept`, `PATCH /team/members/{id}/role`, `DELETE /team/members/{id}`	Team
`GET/POST /api/v1/platform/workspaces`, `POST /workspaces/{id}/switch`	Workspaces
`GET /api/v1/platform/auth/me`	The authenticated identity + workspace
`GET /api/internal/v1/commerce/target-entitlements`	Compute activated for the workspace (first call seeds the default catalog)

Submit a job

POST /api/v1/platform/execution/jobs — send an Idempotency-Key header so a retried request never double-submits or double-reserves. Request body

Field	Type	Notes
`target`	string	Backend id, e.g. `qcos.simulator.statevector`, `gpu.a100-80gb`, `cpu.16vcpu`, a QPU device id
`offer_id`	string	Alternative to `target` (catalog offer id)
`execution_mode`	string	`NATIVE` (default) or `QCOS_OPTIMIZED` (requires a QCOS license)
`instance_id`	string	Quantum instance; its plan decides billing
`workload`	object	The work to run — see workload shapes
`max_estimated_cost_usd`	number	Reject before reserving if the estimate exceeds this
`max_actual_charge_usd`	number	Cap the settled charge (must be ≥ the estimate)
`max_shots`	integer	Reject if shots exceed this
`max_runtime_seconds`	integer	Runtime bound; required for per-minute/per-second targets
`max_gpu_minutes`	number	Cap GPU minutes

The workload object’s main fields: type (QUANTUM_CIRCUIT | GPU_JOB | CPU_JOB), shots, qasm (OpenQASM 2/3, required for circuits unless artifact_uri is given), command, setup, image, kind, resource_type, gpu, num_gpus, cpus, memory_gb, region, cloud. Response (201 new, 200 idempotent replay)

{
  "job_id": "job_a1b2c3d4",
  "status": "CREDIT_RESERVED",
  "execution_mode": "NATIVE",
  "billing_mode": "PREPAID",
  "quantum_instance_id": null,
  "provider_plugin": "qcos",
  "target_id": "qcos.simulator.statevector",
  "shots": 1024,
  "estimated_cost_usd": 0.0,
  "actual_cost_usd": null,
  "credits_remaining": 125.0,
  "provider_job_id": null,
  "status_version": 1,
  "status_reason": "credit_reserved",
  "evidence_hash": null,
  "evidence_signature": null,
  "result_verified": false,
  "reason": "",
  "usage_metrics": null
}

billing_mode is PREPAID, FREE (free instance / free tier) or PAYGO (approved pay-as-you-go, invoiced).
result_verified becomes true only when the job is SETTLED and both the result hash and the evidence hash are recorded — see Evidence.
usage_metrics appears on settled jobs (queue time, QPU seconds, wall clock, shots; provider durations are null rather than fabricated when the provider did not report them).

Poll a job

GET /api/v1/platform/execution/jobs/{id} returns the same object with updated status. Poll until a terminal state.

CREDIT_RESERVED → SUBMITTING → SUBMITTED → PROVIDER_QUEUED → RUNNING → COMPLETED → SETTLED
                                                          ↘ FAILED   ↘ CANCELLED

Fetching an unknown or foreign job id returns 200 with "status": "not_found" in the body rather than an HTTP 404 — check the status field.

Cancel

POST /api/v1/platform/execution/jobs/{id}/cancel asks the provider to abort and releases the unused reservation. A job already at the provider parks in CANCEL_REQUESTED until the abort is confirmed; any shots that actually ran are settled, anything unused is returned. See Run workloads.

Evidence

GET /api/v1/platform/execution/jobs/{id}/evidence (once settled) returns {bundle, hash, signature, algo, key_version, checks} — the hash-pinned record of how the run was produced, with independent verification facets. Full description in Evidence Bundles.

Errors

Refusals return an HTTP status and a machine reason in detail; nothing is charged on a rejection:

{ "detail": "insufficient_credits" }

The complete reason catalog — status codes, meanings and fixes — is in Errors & refusal reasons.

Read-endpoint examples

# prepaid balance
curl -sS https://platform.softquantus.com/api/v1/platform/billing/summary \
  -H "Authorization: Bearer $SQ_API_KEY"

# QPU devices reachable via QCOS
curl -sS https://platform.softquantus.com/api/v1/platform/qcos/backends \
  -H "Authorization: Bearer $SQ_API_KEY"

# recent jobs
curl -sS "https://platform.softquantus.com/api/v1/platform/usage/jobs?page_size=20" \
  -H "Authorization: Bearer $SQ_API_KEY"

# per-job credit ledger
curl -sS "https://platform.softquantus.com/api/v1/platform/usage/ledger?limit=50" \
  -H "Authorization: Bearer $SQ_API_KEY"

Console

Run compute

API & clients

Trust & ecosystem

SoftQuantus Platform REST API reference (/api/v1/platform)

Endpoints

Execution Plane

Usage & billing

Quantum instances

QCOS runtime proxy

Workspace management

Submit a job

Poll a job

Cancel

Evidence

Errors

Read-endpoint examples

​Endpoints

​Execution Plane

​Usage & billing

​Quantum instances

​QCOS runtime proxy

​Workspace management

​Submit a job

​Poll a job

​Cancel

​Evidence

​Errors

​Read-endpoint examples

Endpoints

Execution Plane

Usage & billing

Quantum instances

QCOS runtime proxy

Workspace management

Submit a job

Poll a job

Cancel

Evidence

Errors

Read-endpoint examples