Skip to main content
IBM Quantum Platform
This REST API is only available to On-Prem Plan members who have enabled it in their environment.

IBM Quantum System REST API

The IBM® Quantum System REST API provides direct access to the on-premises quantum computer installed at a client's facilities. The API is deployed locally after integration with the client's infrastructure (typically an HPC environment). The role of the API is to abstract the QPU and the classical runtime's heterogeneous resources. Through this interface, users run workloads on QPUs using Qiskit Runtime primitives, without needing to manage hardware-specific details.

Authentication

You must include an IBM Cloud® Identity and Access Management (IAM) bearer token in the HTTP header of every request. To generate a bearer token, you first need to use the API key you created during your onboarding, as part of the integration process (ask your administrator if you don't have your API key). You then generate the bearer token using the IAM REST API with the following curl 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'

Expected response:

{
   "access_token": "<NEW_BEARER_TOKEN>",
   "refresh_token": "not_supported",
   "token_type": "Bearer",
   "expires_in": 3600,
   "expiration": 1473188353,
   "scope": "ibm_openid"
}
What is a bearer token?

A bearer token is a temporary credential that expires after no more than one hour. After the acquired token expires, you must generate a new one to continue calling IBM Cloud or other service APIs. You can only perform actions that are allowed by your level of assigned access within all accounts.

Use the response property expires_in in the API response to identify how long your specific access token is valid. For more information about bearer tokens, see the IBM Cloud documentation.

Additionally, all requests to the REST API must include the instance’s Cloud Resource Name (CRN) in the request header. You can view the instances you have access to by navigating to the Instances page from the top-left menu and selecting the Direct Access tab. Each instance is listed with its CRN identifier and represents your infrastructure (typically your HPC environment). If you do not have access to this page, contact your administrator.

Submit your bearer token, CRN, and IBM-API-Version on every request within an Authorization and Service-CRN header with this format:

Authorization: Bearer <YOUR_BEARER_TOKEN>
Service-CRN: <YOUR_INSTANCE_CRN>
IBM-API-Version: <YYYY-MM-DD>

Example request:

curl -X 'GET' \
 'https://direct-access-<YOUR_CLIENT_ACRONYM>.quantum-computing.cloud.ibm.com:30060/v1/backends' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
 -H 'Service-CRN: <YOUR_INSTANCE_CRN>' \
 -H 'IBM-API-Version: 2026-02-15'

Submit a job

Note the following when submitting a job:

  • Use the create job operation to submit primitive jobs.
  • You can submit several circuits in a single job as an array of OpenQASM strings representing the circuits.
  • Specify the primitive you want to use with the program_id parameter. Available primitive values are sampler and estimator.
  • When submitting a job to an on-premises QPU, you need to specify your IBM Cloud Direct access instance CRN.
  • You must specify your on-premises quantum system name as the backend name. If you have access to the On-Prem Plan, you can view the backend name in the Compute resources section of IBM Quantum Platform.

Example request creating an Estimator job with one circuit and one observable:

curl -X 'POST' \
'https://direct-access-<YOUR_CLIENT_ACRONYM>.quantum-computing.cloud.ibm.com:30060/v1/jobs' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
-H 'Service-CRN: <YOUR_DIRECT_ACCESS_PLAN_INSTANCE_CRN>' \
-H 'IBM-API-Version: 2026-02-15' \
-H 'Content-Type: application/json' \
--data-raw '{
{
"id": "6e32f594-189e-4bc5-89a2-3c21e1c7e75a",
"program_id": "sampler",
"backend": "ibm_<YOUR_SYSTEM_NAME>",
"timeout_secs": 10000,
"storage": {
 "input": {
   "type": "ibmcloud_cos",
   "region": "us-east",
   "region_type": "regional",
   "bucket_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/abc123:abc123:bucket:my-bucket",
   "object_name": "params:6e32f594-189e-4bc5-89a2-3c21e1c7e75a"
 },
 "results": {
   "type": "ibmcloud_cos",
   "region": "us-east",
   "region_type": "regional",
   "bucket_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/abc123:abc123:bucket:my-bucket",
   "object_name": "results:6e32f594-189e-4bc5-89a2-3c21e1c7e75a"
 },
 "logs": {
   "type": "ibmcloud_cos",
   "region": "us-east",
   "region_type": "regional",
   "bucket_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/abc123:abc123:bucket:my-bucket",
   "object_name": "logs:6e32f594-189e-4bc5-89a2-3c21e1c7e75a"
 }
}
}
}'
Was this page helpful?
Report a bug, typo, or request content on GitHub.