Migrate to the new Qiskit Runtime REST API

As part of the move to the new IBM Quantum® Platform, the Qiskit Runtime REST API on the classic IBM Quantum Platform and the Qiskit Runtime REST API on IBM Cloud® have been combined into one REST API: the Qiskit Runtime REST API.

This guide explains the changes to the REST API and provides suggestions on how to migrate, whether you were previously using either the IBM Cloud or IBM Quantum Platform version.

https://quantum.cloud.ibm.com/api/

Migrate from the Qiskit Runtime on IBM Cloud REST API

If you are moving from the Qiskit Runtime on IBM Cloud REST API, not much has changed for you. The following points are all you need to consider:

• When you call the API, instead of using https://us-east.quantum-computing.cloud.ibm.com/ you must use: https://quantum.cloud.ibm.com/api/.
• All existing endpoints are the same, but now have /v1/ in front. For example, /jobs becomes /v1/jobs.
• There is also one new endpoint: /v1/versions.

For the whole schema, see the Qiskit Runtime API.

Migrate from the Qiskit Runtime REST API on the classic IBM Quantum Platform

If you are moving from the classic Qiskit Runtime REST API, there are two new concepts that are important to understand: Instances and IAM bearer tokens.

Instances

Instances are virtual servers that manage the execution of your workloads, including executing quantum programs and classical compute tasks (such as processing error mitigation). Instances must be specified in the request header by their Cloud Resource Name (CRN).

You can see the instances you have access to on the dashboard, or by clicking the "Instances" tab from the dashboard. Each instance is listed with its CRN identifier. You will need to include this identifier in the header for most of your requests to the REST API.

Authorize requests with IAM bearer tokens

IBM Cloud Identity and Access Management (IAM) bearer tokens are short-lived tokens that are used to authenticate requests to the REST API, and are generated using your account's API key. To generate one, call the IAM Identity Services API as shown in the following sample request:

curl -X POST 'https://iam.cloud.ibm.com/identity/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=MY_APIKEY'

{
   "access_token": "eyJhbGciOiJIUz......sgrKIi8hdFs",
   "refresh_token": "SPrXw5tBE3......KBQ+luWQVY=",
   "token_type": "Bearer",
   "expires_in": 3600,
   "expiration": 1473188353
}

# Use 'service' to invoke operations.
import requests
import json
 
url = 'https://iam.cloud.ibm.com/identity/token'
api_key = 'MY_APIKEY'
headers = {
 'Content-Type': 'application/x-www-form-urlendcoded',
}
data = f'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey={api_key}'
response = requests.post(url, headers=headers, data=data)
 
# Bearer token to authorize requests to the REST API
bearer_token = response.json()['access_token']

Example request using the new REST API

curl -X 'GET' \
   'https://quantum.cloud.ibm.com/api/qiskit-runtime-rest/usage' \
   '-H accept: application/json' \
   '-H authorization: Bearer <BEARER_TOKEN>' \
   '-H Service-CRN: crn:v1:bluemix:public:quantum-computing:us-east:a/b947c1c5a9378d64aed96696e4d76e8e:a3a7f181-35aa-42c8-94d6-7c8ed6e1a94b::'

Changes to the endpoints of the REST API

Many of the endpoints from the REST API on the classic IBM Quantum Platform have either changed or been removed because of this merge. The following sections list the endpoints that are changing, and provide a suggested replacement (if applicable).

For the whole schema, see the Qiskit Runtime API.

Changes to account- and instance-related endpoints

Changes to job-related endpoints

Changes to session- and workload-related endpoints

Changes to system-related endpoints

Changes to analytics- and usage-related endpoints