START NOW
qBraid APIs

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

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

Authentication header

VersionHeader
V1api-key
V2X-API-KEY

Response envelope

The device and job REST responses use a standard envelope:

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

V1 returned raw payloads without this wrapper.

Devices

V2 device objects include paradigm, modality, and pricingModel fields. Device identifiers use qBraid Resource Names (QRNs).

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

V2 job responses use QRNs as identifiers. Job submissions specify the program format instead of 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 /chatDeprecated chat completions
GET /chat/modelsDeprecated chat model listing

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. Replace legacy chat integrations with the AI Gateway. Its OpenAI-compatible and Anthropic-compatible responses use their own formats.
© 2026 qBraid