QuREKA OpenAPI
1. Overview
QuREKA OpenAPI is the external REST API for the QuREKA quantum computing cloud. With a single API key, you can:
- Query available quantum devices (QPUs, emulators)
- Submit OpenQASM 2.0 circuits
- Retrieve execution results
Base URL: https://openapi.qureka.io
Common rules:
- All request/response bodies are JSON, and timestamp fields are epoch milliseconds (long).
- List endpoints support pagination via
page,size, andsortquery parameters, with the total count returned in theX-Total-Countresponse header. - Error responses follow the RFC 7807 Problem Details format.
2. Authentication
Every request requires a QUREKA-API-KEY header. The gateway validates the key and automatically exchanges it for an internal access token, so no separate login process or token refresh is required.
API keys are issued per workspace. Keys are issued per user and per workspace, and every request is automatically scoped to that workspace. There is no need to pass a workspace ID separately in the path or as a parameter.
The typical flow is: check workspace → select device → check credit balance → submit job.
curl https://openapi.qureka.io/api/providers \\
-H "QUREKA-API-KEY: YOUR\_API\_KEY"
API keys are issued from the API Key widget on each workspace's dashboard in the QuREKA console. The key is shown in plaintext only once, at issuance, and cannot be retrieved again afterward. If a key is leaked, it must be reissued immediately.
| Status code | Meaning |
|---|---|
| 401 | Key missing, expired, or disabled |
| 403 | No permission for the requested resource |
3. Workspace
GET /api/workspace — Get my workspace
Returns information about the workspace (tenant) the API key belongs to. Used to validate key validity and determine workspace context.
Response fields:
| Field | Type | Description |
|---|---|---|
| id / name | string | Workspace ID, name |
| personal | boolean | Whether this is a personal workspace |
| memberCount | long | Number of members |
| createdAt | long | Creation timestamp |
curl https://openapi.qureka.io/api/workspace \\
-H "QUREKA-API-KEY: YOUR\_API\_KEY"
Response: 200 success, 401 invalid key
4. Providers & Devices
Query the quantum hardware providers and devices (QPUs, emulators) accessible to the workspace.
GET /api/providers — List providers
Returns all registered quantum hardware providers, paginated.
Query parameters:
| Parameter | Type | Description |
|---|---|---|
| page / size / sort | int / int / string (optional) | Pagination |
| searchField | enum (optional) | NAME, CODE |
| searchKeyword | string (optional) | Search term |
Response (array): id, name, iconPath, desc, createdAt, updatedAt
GET /api/providers/{id} — Get a single provider
Same response schema as the list endpoint. 200 success, 404 provider not found.
GET /api/devices — List available devices
Returns devices accessible to the workspace (published devices with an attached credit policy). This endpoint must be used to confirm a valid deviceCode value before submitting a job.
Query parameters:
| Parameter | Type | Description |
|---|---|---|
| status | enum (optional) | ONLINE, MAINTENANCE |
| type | enum (optional) | QPU, EMULATOR |
| searchField / searchKeyword | enum / string (optional) | NAME, CODE, PROVIDER_NAME |
| page / size / sort | int / int / string (optional) | Pagination |
Response (array):
| Field | Type | Description |
|---|---|---|
| device | Device | Device details (same schema as Get a device) |
| accessRole | enum | ADMIN, USER |
| creditPolicy | CreditPolicy | Billing method (FIXED or VENDOR_DYNAMIC) and credit policy |
Response: 200 success, 403 no workspace access
GET /api/devices/{deviceId} — Get a single device
| Field | Type | Description |
|---|---|---|
| id / name / code | string | Device ID, name, target code (used as deviceCode when submitting a job) |
| type | enum | QPU, EMULATOR |
| qubitCount | int | Number of qubits |
| platform | string | Platform (QPU only) |
| simulationMethods | enum[] | STATE_VECTOR, DENSITY_MATRIX, TENSOR_NETWORK, MPS, CLIFFORD (emulator only) |
| status | enum | ONLINE, MAINTENANCE |
| provider | Provider | Provider details |
| executionWindows | object[] | Available execution time windows — executionDay, windowStartHour, windowEndHour |
| nativeGates | object[] | Native gates — name, description (QPU only) |
| shotsRange | object | Allowed shot range — min, max (QPU only) |
| creditPolicy | CreditPolicy | Linked credit policy |
Response: 200 success, 403 no device access, 404 device not found
5. Credits
Check the workspace's credit balance and track usage history. For fixed-billing (FIXED) devices, credit is pre-deducted per policy at submission time. For dynamically-billed (VENDOR_DYNAMIC) devices, a quote is generated first, and once the quote is confirmed for submission, the confirmed estimated credit amount is deducted.
(Note: SDT's credit system has a dual structure of paid credits and free points. The deduction order is points → subscription credits → purchased credits. The negative-credit repayment scheme has been confirmed as discontinued.)
GET /api/credits/wallet — Get credit balance
Check this before submitting a job to prevent rejection due to insufficient credit.
| Field | Type | Description |
|---|---|---|
| totalCredit | decimal | Total available credit |
| purchaseCredit | decimal | Purchased credit |
| subscriptionCredit | decimal | Subscription credit |
| point | decimal | Bonus points |
| expiringCredit | object? | Next expiring credit — amount, expireAt |
| expiringPoint | object? | Next expiring point — amount, expireAt |
curl https://openapi.qureka.io/api/credits/wallet \\
-H "QUREKA-API-KEY: YOUR\_API\_KEY"
GET /api/credits/histories — Get credit history
Query the workspace's credit transaction history (charges, usage, expiration, refunds).
Query parameters (all optional):
| Parameter | Type | Description |
|---|---|---|
| creditHistoryType | enum[] | Transaction type filter (charge, usage, expiration, refund) |
| createdAtFrom / createdAtTo | long | Time range filter (epoch millis) |
| page / size / sort | int / int / string | Pagination (default sort: createdAt DESC) |
Response (array):
| Field | Type | Description |
|---|---|---|
| id | string | Transaction ID |
| creditHistoryType | enum | Transaction type |
| title | string | Human-readable description |
| credit | decimal | Amount (negative when used) |
| remainingCredit | decimal | Balance after transaction |
| resourceType / resourceId / resourceName | string | Related resource (e.g., device) |
| jobId | string? | Related quantum job (if any) |
| createdAt | long | Transaction timestamp |
| expirationAt | long? | Expiration timestamp of charged credit (if applicable) |
IonQ dynamic billing (VENDOR_DYNAMIC)
For devices such as IonQ, where cost varies by circuit and shot count, billing is not calculated at a fixed rate. Cost is first estimated via an IonQ dry run, and the actual execution is submitted only after confirming the estimated credit amount. Dry runs are not billed.
- Request a cost estimate and poll status until the quote is complete.
- Check the quote's estimated credit, whether debiasing was applied, and its validity period. A quote is valid for 12 hours from completion.
- Submitting a valid quote creates an execution job; upon entering
INITIATEDstatus, the confirmed estimated credit is pre-deducted. - If submission fails (
SUBMIT\_FAILED), the pre-deducted credit is automatically refunded. Submitted jobs and deduction records can be cross-referenced by jobId.
Devices subject to dynamic billing are marked with creditPolicy.pricingMode set to VENDOR\_DYNAMIC. Actual unit prices, exchange rates, discount rates, and calculation formulas are not exposed in the API response.
6. Quantum Jobs
Submit OpenQASM 2.0 circuits, track their status, and retrieve results. Backends (IonQ, IQM, MIMIQ, KREO, etc.) are automatically routed based on deviceCode.
POST /api/quantum-jobs — Submit a job
Submits an OpenQASM 2.0 circuit to the specified fixed-billing (FIXED) device. Credit is pre-deducted according to the device's credit policy, so balance and the device's shot limit should be checked before submission. For IonQ dynamic-billing (VENDOR_DYNAMIC) devices, a quote must first be confirmed via cost estimation, then that quote is submitted.
Request body:
| Field | Type | Description |
|---|---|---|
| deviceCode | string (required) | Target device code — e.g., ionq.forte-1, sdt.qubesim-mimiq |
| circuit | string (required) | OpenQASM 2.0 circuit source |
| shots | int ≥ 1 (required) | Number of measurement shots |
| submissionType | enum (required) | CUDAQ, COMPOSER |
| name | string (optional) | Job name. Auto-generated if omitted |
curl -X POST https://openapi.qureka.io/api/quantum-jobs \\
-H "QUREKA-API-KEY: YOUR\_API\_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"deviceCode": "sdt.qubesim-mimiq",
"circuit": "OPENQASM 2.0;\\ninclude \\"qelib1.inc\\";\\nqreg q\[2\];\\ncreg c\[2\];\\nh q\[0\];\\ncx q\[0\],q\[1\];\\nmeasure q -> c;",
"shots": 1000,
"submissionType": "COMPOSER"
}'
Response (201 Created):
{
"id": "3f9c1a2e-...", // QuREKA job ID — used for subsequent queries
"jobId": "a81b7c...", // External backend job ID
"jobStatus": "SUBMITTED"
}
Response: 201 submitted, 400 parameter error (circuit syntax, shot range, etc.)
GET /api/quantum-jobs — List jobs
Query the workspace's jobs with filtering, search, and pagination.
Visibility scope depends on role. If the API key belongs to a workspace admin, all jobs in the workspace are returned. If it belongs to a regular member, only that user's own jobs are returned; this is enforced server-side and cannot be bypassed via parameters. An admin who wants to narrow results to a specific user can filter with searchField=USER\_NAME&searchKeyword=....
Query parameters (all optional):
| Parameter | Type | Description |
|---|---|---|
| deviceType | enum | QPU, EMULATOR |
| jobStatuses | enum[] | INITIATED, SUBMITTED, RUNNING, DONE, FAILED, SUBMIT_FAILED, CANCELLED, STOPPED, UNKNOWN |
| submissionType | enum | CUDAQ, COMPOSER |
| jobQubitsFrom/To, jobShotsFrom/To | int | Qubit and shot range |
| createdAtFrom/To, submittedAtFrom/To, completedAtFrom/To | long | Time range filters (epoch millis) |
| searchField + searchKeyword | enum + string | USER_NAME, PROVIDER_NAME, DEVICE_NAME, DEVICE_CODE, JOB_ID |
| page / size / sort | int / int / string | Pagination |
Response is an array of the same Job object as Get a job; total count is returned in the X-Total-Count header.
GET /api/quantum-jobs/{id} — Get a single job
If the job is in SUBMITTED or RUNNING status, the latest status is synchronized from the backend at request time, so this endpoint can safely be used for polling.
Key response fields:
| Field | Type | Description |
|---|---|---|
| id / jobId | string | QuREKA job ID, external backend job ID |
| jobStatus | enum | INITIATED → SUBMITTED → RUNNING → DONE / FAILED / SUBMIT_FAILED / CANCELLED / STOPPED |
| deviceCode / deviceName / deviceType / providerName | string | Execution device details |
| jobQubits / jobShots | int | Number of qubits, shots |
| jobCircuit | string | Submitted circuit source |
| jobResult | string | Raw backend result (use Get job results for structured output) |
| errorMessage | string? | Error message on failure |
| createdAt / submittedAt / startedAt / completedAt | long | Lifecycle timestamps |
| preChargedAmount / usedCredit | decimal | Pre-deducted amount, used credit. For dynamically-billed jobs, this records the confirmed quote credit |
| tenantId / tenantName / userId / userName | string | Ownership information |
Response: 200 success, 404 job not found
GET /api/quantum-jobs/{id}/result — Get structured results
Automatically detects the backend's native result format (Braket JSON, MIMIQ JSON, etc.) and returns probability distributions, measurement counts, and state vectors as a unified JSON. Used for visualization and post-processing.
{
"probabilities": { "00": 0.503, "11": 0.497 },
"counts": { "00": 503, "11": 497 },
"stateVector": \[
{ "basis": "00", "real": 0.7071, "imag": 0,
"amplitude": "0.7071+0.0000i", "probability": 0.5 }
\],
"metadata": {
"providerName": "SDT", "deviceName": "QubeSim MIMIQ",
"qubits": 2, "shots": 1000,
"isPartialResult": false, "fidelity": 0.999
}
}
(stateVector is included only in emulator results.)
Response: 200 result returned, 400 resultNotReady (result not yet generated), 404 job not found
GET /api/quantum-jobs/{id}/download — Download results
Downloads the job result as a plain text file (text/plain, attachment). Filename convention: job\_result\_{jobId}\_{yyyy-MM-dd}.txt
Response: 200 download, 400 resultEmpty (no result), 404 job not found
7. Enum reference
| Enum | Values |
|---|---|
| JobStatus | INITIATED, SUBMITTED, RUNNING, DONE, FAILED, SUBMIT_FAILED, CANCELLED, STOPPED, UNKNOWN |
| JobSubmissionType | CUDAQ, COMPOSER |
| JobLanguage | OPENQASM_20 |
| DeviceType | QPU, EMULATOR |
| DeviceStatus | ONLINE, MAINTENANCE |
| SimulationMethod | STATE_VECTOR, DENSITY_MATRIX, TENSOR_NETWORK, MPS, CLIFFORD |
| DeductionType (credit) | TASK, SHOT, TIME |
| PricingMode (credit) | FIXED, VENDOR_DYNAMIC |
---
8. Using the CUDA-Q client (qubestack-cudaq)
Instead of calling the REST API directly, in an NVIDIA CUDA-Q environment you can submit jobs to the same Job Engine through the QuREKA backend plugin qubestack-cudaq. This package internally handles the REST API calls (job submission, polling, result retrieval) on your behalf.
Distribution
qubestack-cudaq is publicly distributed via PyPI (Python Package Index).
- PyPI page: https://pypi.org/project/qubestack-cudaq/
- Latest version: 1.0.86 (as of the 2026-07-21 release — confirmation needed: re-verify the latest version at time of publication)
- License: Apache License 2.0
- Distributed by: SDT Inc.
- Requirement: Python 3.12 or higher
Installation
No separate registration or internal repository access is required; it can be installed directly from public PyPI.
pip install qubestack-cudaq
cuda-quantum-cu12==0.14.0 is installed automatically as a dependency.
Verify installation:
pip show qubestack-cudaq
To install a specific version:
pip install qubestack-cudaq==1.0.86
The Academic notebook comes pre-included in the qubestack-pad notebook image.
Version compatibility matrix
The four packages qubestack-cudaq, cuda-quantum-cu12, cudaq-qec, and cudaq-solvers must be distributed together as ABI-compatible versions. This is enforced by the qubestack-cudaq CI via scripts/verify\_academic.sh.
| qubestack-cudaq | cuda-quantum-cu12 | cudaq-qec | cudaq-solvers |
|---|---|---|---|
| 1.0.x (current) | 0.14.0 | 0.6.0 | 0.6.0 |
(Internal note: an internal tracking document exists explaining the rationale for version pinning and the criteria for adding new rows. Since this is an external document, the ticket number has not been exposed — confirmation needed.)
Quick start
import cudaq
# Configure QuREKA target
cudaq.set\_target("qureka", backend="sdt.qubesim-mimiq", api\_key="YOUR\_API\_KEY")
# Define quantum kernel
@cudaq.kernel
def bell\_state():
q = cudaq.qvector(2)
h(q\[0\])
cx(q\[0\], q\[1\])
mz(q)
# Execute
result = cudaq.sample(bell\_state, shots\_count=1000)
print(result)
(Note: set\_target is a setting used to designate the QuREKA backend for QPU submission and management purposes — it is not for local CPU/GPU simulation.)
Supported backends
| Backend | Identifier |
|---|---|
| QPerfect MIMIQ | sdt.qubesim-mimiq |
| IQM Garnet | iqm.garnet |
| IQM Emerald | iqm.emerald |
| IonQ Forte (direct IonQ Cloud v0.4 connection) | ionq.forte-1 |
| SDT KREO | sdt.kreo-sc20 |
Configuration parameters
| Parameter | Required | Description |
|---|---|---|
| backend | Required | Quantum backend identifier (see table above) |
| api_key | Required | QuREKA API key |
| option | Optional | Backend-specific options (JSON string) |
License: Apache License 2.0
---
Items requiring confirmation
- Discrepancy between the actual implementation state of the deployed Swagger UI and this document (v1 target spec)
- How to summarize the internal rationale document for version pinning for external use, without exposing the ticket number
- Whether the term "simulation" as used by CUDA-Q Academic conflicts with SDT's internal terminology standard (emulation/emulator terminology; simulator/simulation prohibited) — since the original term is NVIDIA's own terminology (CUDA-Q, GPU simulation), it should be distinguished from SDT's own usage
- Whether a concrete JSON schema example is needed for the option parameter (backend-specific options)