Documentation Index
Fetch the complete documentation index at: https://docs.qbraid.com/llms.txt
Use this file to discover all available pages before exploring further.
This guide covers breaking changes when migrating from the qBraid V1 API to V2.
What’s Changed
Authentication and Response Structure
Base URL
| Version | Base URL |
|---|
| V1 | https://api.qbraid.com/api |
| V2 | https://api-v2.qbraid.com/api/v1 |
| Version | Header |
|---|
| V1 | api-key |
| V2 | X-API-KEY |
Response Envelope
V2 responses are wrapped in a standard envelope:
{
"success": boolean,
"data": { ... }
}
Devices
The new API v2 makes the device objects more descriptive and standardized. We include fields like paradigm, modality, and pricingModel to better categorize devices. We have also standardized the device identifiers to use QRNs (qBraid Resource Names) for consistency across the platform.
Routes
| Operation | V1 Route | V2 Route |
|---|
| List devices | GET /quantum-devices | GET /devices |
| Get device | — | GET /devices/{device_qrn} |
Identifier
| Version | Field | Example |
|---|
| V1 | qbraidDeviceId | qbraid_qir_simulator |
| V2 | qrn (QRN format) | qbraid:qbraid:sim:qir-sv |
Response Fields
V2 adds:
| Field | Description |
|---|
qrn | QRN identifier |
paradigm | gate_model, analog, annealing, other |
modality | Device modality (e.g., sparse_simulator) |
pricingModel | fixed or dynamic |
pricing | Object with perTask, perShot, perMinute |
directAccess | Boolean for direct device access |
runInputTypes | Array of supported input formats |
type → deviceType (values: SIMULATOR, QPU)
Jobs
Quantum jobs responses have been re-organized and use QRNs as identifiers. The job submission format has also changed to explicitly specify the program format rather than using the openQasm or bitcode fields.
Routes
| Operation | V1 Route | V2 Route |
|---|
| Create job | POST /quantum-jobs | POST /jobs |
| Get job | GET /quantum-jobs | GET /jobs/{job_qrn} |
| Get result | GET /quantum-jobs/result/:id | GET /jobs/{job_qrn}/result |
| Get program | — | GET /jobs/{job_qrn}/program |
| Cancel job | PUT /quantum-jobs/cancel/:id | POST /jobs/{job_qrn}/cancel |
| Delete job | — | DELETE /jobs/{job_qrn} |
| Delete multiple jobs | DELETE /quantum-jobs/:ids | DELETE /jobs?qrns=[...] |
Request Body
V1:
{
"qbraidDeviceId": "qbraid_qir_simulator",
"openQasm": "OPENQASM 3; ...",
"shots": 1000,
"tags": {}
}
{
"deviceQrn": "qbraid:qbraid:sim:qir-sv",
"program": {
"format": "qasm3",
"data": "OPENQASM 3; ..."
},
"shots": 1000,
"tags": {}
}
qbraidDeviceId → deviceQrn (QRN format)openQasm/bitcode → program.data with explicit program.formatcircuitNumQubits removed (inferred from program)
Response Fields
V2 adds these fields to job responses:
| Field | Description |
|---|
jobQrn | QRN identifier (replaces V1’s _id) |
batchJobQrn | Batch job reference |
experimentType | gate_model, analog, annealing, other |
estimatedCost | Pre-execution cost estimate |
timeStamps | Object with createdAt, endedAt, executionDuration |
metadata | Extensible metadata object |
What’s the Same
- API key authentication model (header-based)
- Core job lifecycle: create → poll status → get result
shots, tags, status fields- Job statuses:
INITIALIZING, QUEUED, RUNNING, COMPLETED, FAILED, CANCELLED
- Device statuses:
ONLINE, OFFLINE, UNAVAILABLE
Deprecated Endpoints
The following V1 endpoints are not available in V2:
| Endpoint | Notes |
|---|
POST /chat | Chat completions — deprecated |
GET /chat/models | Chat model listing — deprecated |
Quick Migration Checklist
- Update base URL to
https://api-v2.qbraid.com/api/v1
- Change auth header from
api-key to X-API-KEY
- Replace
qbraidDeviceId with deviceQrn using QRN format
- Wrap program in
{ "format": "...", "data": "..." } object
- Update route paths (
/quantum-jobs → /jobs, /quantum-devices → /devices)
- Handle new response envelope (
response.data instead of raw payload)
- Remove any chat endpoint integrations
