> ## 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.

# 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:

```json theme={null}
{
  "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:**

```json theme={null}
{
  "qbraidDeviceId": "qbraid_qir_simulator",
  "openQasm": "OPENQASM 3; ...",
  "shots": 1000,
  "tags": {}
}
```

**V2:**

```json theme={null}
{
  "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