Skip to main content
This guide covers breaking changes when migrating from the qBraid V1 API to V2.

​
What’s Changed

​
Authentication and Response Structure

​
Base URL

VersionBase URL
V1https://api.qbraid.com/api
V2https://api-v2.qbraid.com/api/v1

​
Authentication Header

VersionHeader
V1api-key
V2X-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

OperationV1 RouteV2 Route
List devicesGET /quantum-devicesGET /devices
Get device—GET /devices/{device_qrn}

​
Identifier

VersionFieldExample
V1qbraidDeviceIdqbraid_qir_simulator
V2qrn (QRN format)qbraid:qbraid:sim:qir-sv

​
Response Fields

V2 adds:
FieldDescription
qrnQRN identifier
paradigmgate_model, analog, annealing, other
modalityDevice modality (e.g., sparse_simulator)
pricingModelfixed or dynamic
pricingObject with perTask, perShot, perMinute
directAccessBoolean for direct device access
runInputTypesArray 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

OperationV1 RouteV2 Route
Create jobPOST /quantum-jobsPOST /jobs
Get jobGET /quantum-jobsGET /jobs/{job_qrn}
Get resultGET /quantum-jobs/result/:idGET /jobs/{job_qrn}/result
Get program—GET /jobs/{job_qrn}/program
Cancel jobPUT /quantum-jobs/cancel/:idPOST /jobs/{job_qrn}/cancel
Delete job—DELETE /jobs/{job_qrn}
Delete multiple jobsDELETE /quantum-jobs/:idsDELETE /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:
FieldDescription
jobQrnQRN identifier (replaces V1’s _id)
batchJobQrnBatch job reference
experimentTypegate_model, analog, annealing, other
estimatedCostPre-execution cost estimate
timeStampsObject with createdAt, endedAt, executionDuration
metadataExtensible 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:
EndpointNotes
POST /chatChat completions — deprecated
GET /chat/modelsChat 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