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, and sort query parameters, with the total count returned in the X-Total-Count response 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.

1. Request a cost estimate and poll status until the quote is complete.
2. Check the quote's estimated credit, whether debiasing was applied, and its validity period. A quote is valid for 12 hours from completion.
3. Submitting a valid quote creates an execution job; upon entering INITIATED status, the confirmed estimated credit is pre-deducted.
4. 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)