Runtime API Lifecycle and Compatibility Governance

The runtime API is where quantum capability becomes a product. It exposes execution modes, primitive interfaces, backend access, job submission, sessions, batches, results, errors, quotas, and evidence contracts. IBM’s Qiskit Runtime REST API, for example, exposes operations for running primitives on QPUs and for retrieving information about accessible instances and QPUs [R246]. That is not just a convenience interface. It is a governed operating boundary.

Diagram loads as you read

Runtime API Lifecycle and Compatibility Governance · Figure 1

View diagram source

flowchart LR
    Client[Client SDK or API caller] --> Gateway[Runtime gateway]
    Gateway --> Auth[Identity and entitlement]
    Auth --> Contract[Runtime contract]
    Contract --> Scheduler[Scheduler]
    Scheduler --> QPU[QPU or simulator]
    QPU --> Result[Result and evidence]

Runtime API surfaces

Surface	Compatibility obligation
submission	stable job schema, mode selection, target selection
execution mode	stable semantics for job, batch, session, reservation, or local mode
error model	predictable error codes and retry classification
evidence	stable result package schema and artifact references
quota	visible usage counters and enforcement reasons
cancellation	explicit request, pending, terminal, and failure states; documented cleanup and billing behavior
result retrieval	stable pagination, retention, and authorization semantics

Diagram loads as you read

Runtime API surfaces · Figure 2

View diagram source

flowchart TB
    API[Runtime API] --> Submit[Submit]
    API --> Mode[Execution mode]
    API --> Error[Error model]
    API --> Evidence[Evidence]
    API --> Quota[Quota]
    API --> Cancel[Cancel]
    API --> Retrieve[Retrieve]

Qiskit Runtime documents job, batch, and session modes as different scheduling strategies for different workload shapes [R246]. A platform wrapper should preserve those differences explicitly instead of hiding them behind one generic run() call.

Compatibility window

A runtime API change must go through a compatibility window when it affects execution semantics, scheduling behavior, error mitigation defaults, result schema, or quota accounting.

Diagram loads as you read

Compatibility window · Figure 3

View diagram source

sequenceDiagram
    participant Dev as Runtime team
    participant Broker as Broker gateway
    participant Canary as Canary users
    participant Evidence as Evidence store
    participant Board as Change board
    Dev->>Broker: Publish new API version
    Broker->>Canary: Route limited traffic
    Canary->>Evidence: Produce comparison packages
    Evidence->>Board: Summarize deltas
    Board-->>Broker: Promote, hold, or rollback

API lifecycle states

Diagram loads as you read

API lifecycle states · Figure 4

View diagram source

stateDiagram-v2
    [*] --> Draft
    Draft --> Preview
    Preview --> Supported
    Supported --> Deprecated
    Deprecated --> Retired
    Preview --> Withdrawn
    Deprecated --> ExtendedSupport
    ExtendedSupport --> Retired

Version contract

Versioning must cover more than endpoint paths. It should include:

schema version
primitive version
mode semantics
backend target model version
mitigation-default version
evidence-package version
quota-accounting version
error-code taxonomy

Diagram loads as you read

Version contract · Figure 5

View diagram source

classDiagram
    class RuntimeContract {
      api_version
      primitive_version
      mode_semantics
      target_model_version
      mitigation_profile
      evidence_schema
      quota_model
      error_taxonomy
    }
    class Workload {
      workload_id
      owner
      requested_mode
      requested_target
    }
    Workload --> RuntimeContract

Contract testing

Every runtime release needs contract tests for each supported workload class.

Diagram loads as you read

Contract testing · Figure 6

View diagram source

flowchart LR
    Spec[Runtime API spec] --> Generate[Generate contract tests]
    Generate --> Local[Local simulator tests]
    Generate --> Shadow[Shadow provider tests]
    Local --> Compare[Compare results]
    Shadow --> Compare
    Compare --> Decision{Compatible?}

Design rule

Expose runtime modes as first-class concepts. Job, batch, session, and reservation have different cost, latency, fairness, and reproducibility implications. Hiding them makes the API simpler while making operations less trustworthy.

Additional technical sources: [R255].