Migrating from V1

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

Authentication Header

Version	Header
V1	api-key
V2	X-API-KEY

Response Envelope

V2 responses are wrapped in a standard envelope:

{
  "success": boolean,
  "data": { ... }
}

V1 returned raw payloads without this wrapper.

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

V2 renames:

• 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": {}
}

V2:

{
  "deviceQrn": "qbraid:qbraid:sim:qir-sv",
  "program": {
    "format": "qasm3",
    "data": "OPENQASM 3; ..."
  },
  "shots": 1000,
  "tags": {}
}

Key differences:

• qbraidDeviceId → deviceQrn (QRN format)
• openQasm/bitcode → program.data with explicit program.format
• circuitNumQubits 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

1. Update base URL to https://api-v2.qbraid.com/api/v1
2. Change auth header from api-key to X-API-KEY
3. Replace qbraidDeviceId with deviceQrn using QRN format
4. Wrap program in { "format": "...", "data": "..." } object
5. Update route paths (/quantum-jobs → /jobs, /quantum-devices → /devices)
6. Handle new response envelope (response.data instead of raw payload)
7. Remove any chat endpoint integrations