What this plugin is

This is a project plugin you copy into an Unreal project. Its Blueprint async actions send HTTP requests and then return either On Success with a response or On Error with a safe error object.

White execution pins control when the request starts.

Request pins are forms you fill out before sending the request.

Options is for advanced per-call auth or proxy overrides. Leave it empty for normal project settings.

The plugin never stores or edits IBM credentials and never logs credential values.

Configure

Start with Backend Proxy for shipped games. Direct API Key is only for local development, demos, and game jams because a key packaged into a game client can be extracted.

[/Script/QuantumApi.QuantumApiSettings] AuthMode=BackendProxy ApiKey= bUseEnvironmentApiKey=True ApiKeyEnvironmentVariable=QUANTUM_API_KEY BearerToken= DefaultIbmProfile= RequestTimeoutSeconds=10.000000 MaxReadRetries=2 MaxRetryDelaySeconds=5.000000

The base URL is the web address the plugin sends requests to. The hosted Quantum API address is already configured, so leave it alone unless you run your own service. A self-hosted project can set BaseUrl in Config/DefaultGame.ini.

First Blueprint call: Health Check

Use Health Check before building bigger flows. It confirms that the service is reachable and needs no request body.

Options

Leave empty unless you are testing a one-off bearer token, API key, or custom proxy header.

On Success

Read fields such as status, service, version, runtime mode, and whether Qiskit is available.

On Error

Route FQuantumApiError to UI or logs without freezing gameplay.

Run Circuit explained pin-by-pin

“What does ‘array of Quantum Api Circuit Operation’ mean?”

It means "a list of gate steps." A struct is a bundle of fields, an array is a list, and each Quantum Api Circuit Operation is one instruction such as "apply an H gate to qubit 0."

Use Run Circuit when you want a multi-step circuit. In plain English, you are saying: create this many qubits, run this ordered list of gate operations, then sample the circuit this many times.

Request Circuit Num Qubits

How many qubits, or wires, the circuit has. Start with 1.

Request Circuit Operations

The ordered list of gate steps. Start with one operation: Gate = h, Target = 0.

Request Shots

How many times to sample the circuit. Start with 1024.

Request Include Statevector

Advanced simulator output. Leave unchecked at first.

Request Send Seed

Whether to send a deterministic simulator seed. Leave unchecked at first.

Request Seed

Only matters when Request Send Seed is checked.

Options

Optional per-call auth or proxy overrides. Leave empty for normal project settings.

Each circuit operation has Gate, Target, optional Theta for rotation gates like rx, ry, and rz, and optional Control for controlled gates like cx.

Tiny first circuit

Num Qubits: 1

Operations: one operation with Gate = h and Target = 0

Shots: 1024

Include Statevector: unchecked

Send Seed: unchecked

IBM hardware jobs

The plugin submits jobs by profile name. The IBM token and instance stay on the Quantum API service, not inside the game. Set Default IBM Profile Name in Project Settings or fill the request struct's IbmProfile.

Use List Backends with Provider = ibm to discover a backend name.

Submit Random Job, Submit Circuit Job, or Submit QASM Job with the backend name and profile name.

Poll Get Job Status, then read Get Job Result. Use Cancel Job when needed.

IBM hardware jobs have to wait in a queue before starting; get started at https://quantum.cloud.ibm.com/. Hardware availability, account access, queue time, and usage limits still apply.

Auth modes: Direct API Key vs Backend Proxy

Backend Proxy

Recommended for shipped games. Your backend holds the upstream API key and can accept bearer or custom headers from the plugin.

Direct API Key (Development Only)

For local development, demos, and game jams. It sends X-API-Key from the environment, Plugin Settings, or one request's Options.

Options

Use Override Api Key, Override Bearer Token, or Extra Headers only when one call needs different auth than the project settings.

Restart Unreal after changing QUANTUM_API_KEY. Never ship a packaged client with a real upstream key.

All Blueprint nodes

Typed success payloads

Health Check

Run Gate

Transform Text

Generate Random Int

Named JSON-result async actions

Get Echo Types

Run Circuit

List Backends

Transpile

Import QASM

Export QASM

Run QASM

Submit Circuit Job

Submit QASM Job

Submit Random Job

Get Job Status

Get Job Result

Cancel Job

Advanced JSON actions

Grover Search

Amplitude Estimation

Phase Estimation

Time Evolution

QAOA

VQE

MaxCut

Knapsack

Traveling Salesperson

State Tomography

Randomized Benchmarking

Quantum Volume

T2 Ramsey

Portfolio Optimization

Portfolio Diversification

Kernel Classifier

VQC Classifier

QSVR Regressor

Ground State Energy

Fermionic Mapping Preview

Troubleshooting

If a node errors immediately, run Health Check first and confirm that the configured base URL or proxy is reachable.

If Run Circuit feels confusing, start with Run Gate, then Generate Random Int, then one h operation targeting qubit 0.

If IBM hardware does not run, check the profile name, backend availability, account access, queue time, and service-side IBM configuration.

GET health, backend, and job reads retry limited transport and transient-server failures. POSTs and cancellation do not retry automatically.

Quantum API Unreal Plugin

QuantumApi is a UE 5.8 Runtime plugin that gives Blueprints asynchronous nodes for Quantum API requests. Use it to call simulations, random helpers, QASM tools, and hardware jobs without blocking the game thread.

Runtime / package

UE 5.8 Runtime plugin

Version

0.2.0-beta

On this page

What this plugin is Install Configure First Blueprint call: Health Check Run Gate example Generate Random Int example Run Circuit explained pin-by-pin IBM hardware jobs Auth modes: Direct API Key vs Backend Proxy All Blueprint nodes Troubleshooting

What this plugin is

This is a project plugin you copy into an Unreal project. Its Blueprint async actions send HTTP requests and then return either On Success with a response or On Error with a safe error object.

White execution pins control when the request starts.

Request pins are forms you fill out before sending the request.

Options is for advanced per-call auth or proxy overrides. Leave it empty for normal project settings.

The plugin never stores or edits IBM credentials and never logs credential values.

Install

Copy sdk/unreal into <YourProject>/Plugins/QuantumApi.

Regenerate project files, build the project, then enable Quantum API in Unreal's Plugin Browser if Unreal asks.

Keep game-specific configuration in the host project's Config/DefaultGame.ini.

Configure

Start with Backend Proxy for shipped games. Direct API Key is only for local development, demos, and game jams because a key packaged into a game client can be extracted.

First Blueprint call: Health Check

Use Health Check before building bigger flows. It confirms that the service is reachable and needs no request body.

Options

Leave empty unless you are testing a one-off bearer token, API key, or custom proxy header.

On Success

Read fields such as status, service, version, runtime mode, and whether Qiskit is available.

On Error

Route FQuantumApiError to UI or logs without freezing gameplay.

Run Gate example

Run Gate is the easiest quantum-flavored test after Health Check. For a first rotation, use these request values:

GateType

rotation

bSendRotationAngle

Checked / true

RotationAngleRad

1.57079632679, which is PI / 2

On success, read Measurement. It is usually 0 or 1.

Generate Random Int example

Generate Random Int calls POST /v1/random with inclusive signed 32-bit bounds. For a coin-flip-style test, set Min = 0 and Max = 1.

The response includes Value and Source. The source may be qiskit-simulator or classical-fallback; neither is a cryptographic-randomness guarantee.

Run Circuit explained pin-by-pin

“What does ‘array of Quantum Api Circuit Operation’ mean?”

It means "a list of gate steps." A struct is a bundle of fields, an array is a list, and each Quantum Api Circuit Operation is one instruction such as "apply an H gate to qubit 0."

Use Run Circuit when you want a multi-step circuit. In plain English, you are saying: create this many qubits, run this ordered list of gate operations, then sample the circuit this many times.

Request Circuit Num Qubits

How many qubits, or wires, the circuit has. Start with 1.

Request Circuit Operations

The ordered list of gate steps. Start with one operation: Gate = h, Target = 0.

Request Shots

How many times to sample the circuit. Start with 1024.

Request Include Statevector

Advanced simulator output. Leave unchecked at first.

Request Send Seed

Whether to send a deterministic simulator seed. Leave unchecked at first.

Request Seed

Only matters when Request Send Seed is checked.

Options

Optional per-call auth or proxy overrides. Leave empty for normal project settings.

Each circuit operation has Gate, Target, optional Theta for rotation gates like rx, ry, and rz, and optional Control for controlled gates like cx.

Tiny first circuit

Num Qubits: 1

Operations: one operation with Gate = h and Target = 0

Shots: 1024

Include Statevector: unchecked

Send Seed: unchecked

IBM hardware jobs

Use List Backends with Provider = ibm to discover a backend name.

Submit Random Job, Submit Circuit Job, or Submit QASM Job with the backend name and profile name.

Poll Get Job Status, then read Get Job Result. Use Cancel Job when needed.

IBM hardware jobs have to wait in a queue before starting; get started at https://quantum.cloud.ibm.com/. Hardware availability, account access, queue time, and usage limits still apply.

Auth modes: Direct API Key vs Backend Proxy

Backend Proxy

Recommended for shipped games. Your backend holds the upstream API key and can accept bearer or custom headers from the plugin.

Direct API Key (Development Only)

For local development, demos, and game jams. It sends X-API-Key from the environment, Plugin Settings, or one request's Options.

Options

Use Override Api Key, Override Bearer Token, or Extra Headers only when one call needs different auth than the project settings.

Restart Unreal after changing QUANTUM_API_KEY. Never ship a packaged client with a real upstream key.

All Blueprint nodes

Typed success payloads

Health Check

Run Gate

Transform Text

Generate Random Int

Named JSON-result async actions

Get Echo Types

Run Circuit

List Backends

Transpile

Import QASM

Export QASM

Run QASM

Submit Circuit Job

Submit QASM Job

Submit Random Job

Get Job Status

Get Job Result

Cancel Job

Advanced JSON actions

Grover Search

Amplitude Estimation

Phase Estimation

Time Evolution

QAOA

VQE

MaxCut

Knapsack

Traveling Salesperson

State Tomography

Randomized Benchmarking

Quantum Volume

T2 Ramsey

Portfolio Optimization

Portfolio Diversification

Kernel Classifier

VQC Classifier

QSVR Regressor

Ground State Energy

Fermionic Mapping Preview

Troubleshooting

If a node errors immediately, run Health Check first and confirm that the configured base URL or proxy is reachable.

If Run Circuit feels confusing, start with Run Gate, then Generate Random Int, then one h operation targeting qubit 0.

If IBM hardware does not run, check the profile name, backend availability, account access, queue time, and service-side IBM configuration.

GET health, backend, and job reads retry limited transport and transient-server failures. POSTs and cancellation do not retry automatically.

Feedback, contributions, comments, and questions

Questions, corrections, and issue reports are welcome. Email DavidJGrimsley@gmail.com or open an issue at github.com/davidjgrimsley/quantum-api/issues.

Agent version (.md)

Coding agents can use the plain Markdown companion for this guide at /public-facing/api/quantum/ue-plugin.md. For best results, also point the agent at /llms.txt so it can discover the core API guide, OpenAPI references, and the other integration guides.