IBM Quantum Negotiate Version and List Backends

arazzo: 1.0.1
info:
  title: IBM Quantum Negotiate Version and List Backends
  summary: Discover the live API version, then list accessible backends and check one backend's status using that version.
  description: >-
    A version-negotiation bootstrap flow. The workflow first queries the
    supported API versions to learn which version is live, then uses the
    caller-supplied version header to list the backends the instance can reach
    and to read the status of a chosen backend. This mirrors the recommended
    practice of pinning the IBM-API-Version header to a known-good value before
    issuing data-plane calls. Each data-plane request inlines its bearer token,
    Service-CRN, and IBM-API-Version headers so the flow can be read and executed
    without opening the underlying OpenAPI descriptions.
  version: 1.0.0
sourceDescriptions:
- name: backendsApi
  url: ../openapi/ibm-quantum-backends-api-openapi.yml
  type: openapi
- name: versionsApi
  url: ../openapi/ibm-quantum-versions-api-openapi.yml
  type: openapi
workflows:
- workflowId: negotiate-version-and-list-backends
  summary: Read available API versions, then list backends and check one backend's status.
  description: >-
    Fetches the supported API versions, lists accessible backends, and reads the
    status of a chosen backend.
  inputs:
    type: object
    required:
    - accessToken
    - serviceCrn
    - apiVersion
    - backend
    properties:
      accessToken:
        type: string
        description: IBM Cloud IAM bearer token used in the Authorization header.
      serviceCrn:
        type: string
        description: IBM Cloud Service CRN identifying the Qiskit Runtime instance.
      apiVersion:
        type: string
        description: API version date sent in the IBM-API-Version header (e.g. 2026-03-15).
      backend:
        type: string
        description: Name of the backend whose status to read.
  steps:
  - stepId: getVersions
    description: >-
      Query the list of supported API versions so the caller can confirm the
      version it intends to pin is still live.
    operationId: get_versions
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: Service-CRN
      in: header
      value: $inputs.serviceCrn
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      versions: $response.body#/versions
  - stepId: listBackends
    description: >-
      List the backends the instance can access, using the pinned API version
      header.
    operationId: list_backends
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: Service-CRN
      in: header
      value: $inputs.serviceCrn
    - name: IBM-API-Version
      in: header
      value: $inputs.apiVersion
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      devices: $response.body#/devices
  - stepId: getBackendStatus
    description: >-
      Read the status of the chosen backend, including its operational state and
      queue length.
    operationId: get_backend_status
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: Service-CRN
      in: header
      value: $inputs.serviceCrn
    - name: IBM-API-Version
      in: header
      value: $inputs.apiVersion
    - name: id
      in: path
      value: $inputs.backend
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      backendState: $response.body#/state
      queueLength: $response.body#/length_queue
  outputs:
    versions: $steps.getVersions.outputs.versions
    devices: $steps.listBackends.outputs.devices
    queueLength: $steps.getBackendStatus.outputs.queueLength