Quantum API TypeScript SDK
v0.1.2
TypeScript package. Use this typed client in browser, Expo, and Node.js apps. It handles the API address and request headers for runtime calls and jobs.
Downloads, source, and demos
Support the Quantum API work
These guides, SDKs, plugins, and demos take real testing time across engines and package ecosystems.
What this SDK is
@mr.dj2u/quantum-api is a TypeScript client for browser, Expo, and Node.js apps. It exposes named methods instead of making you build every URL and header yourself. The examples below use a trusted Node.js environment for protected calls.
Install
npm install "@mr.dj2u/quantum-api"
Get the published package from npm. It supports ESM and CommonJS. Use a runtime with fetch, such as Node.js 18 or later, or supply your own fetch implementation.
Configure
The published SDK requires a baseUrl when creating the client. Use the Quantum API address shown below; the SDK adds /v1 for you.
import { QuantumApiClient } from "@mr.dj2u/quantum-api";
const client = new QuantumApiClient({
baseUrl: "https://davidjgrimsley.com/public-facing/api/quantum",
});
This client can make public calls such as Health Check. For protected calls in trusted server code, also pass a server-only API key. In a public app, use your backend proxy and do not bundle the key.
First call: Health Check
const health = await client.health();
console.log(health.status, health.runtime_mode);
Health is public. It is the smallest useful check before making an authenticated runtime call.
Run Gate example
const gate = await client.runGate({
gate_type: "rotation",
rotation_angle_rad: Math.PI / 2,
});
console.log(gate.measurement);
Auth modes
Public
Health and portfolio metadata do not require credentials.
API key
Most runtime methods use X-API-Key. Pass apiKey when creating the client.
Per-call override
Pass auth options to a method only when that call needs different credentials.
IBM profiles and jobs
Use an IBM profile already configured for your API key, or the account default. Choose an available IBM backend, submit a circuit job, then poll its status and fetch the result when it succeeds. Submission alone does not mean hardware ran.
IBM hardware jobs have to wait in a queue before starting; get started at quantum.cloud.ibm.com.
const trustedClient = new QuantumApiClient({
baseUrl: "https://davidjgrimsley.com/public-facing/api/quantum",
apiKey: serverSecrets.quantumApiKey,
});
const job = await trustedClient.submitCircuitJob({
provider: "ibm",
backend_name: "YOUR_AVAILABLE_IBM_BACKEND",
ibm_profile: "YOUR_EXISTING_PROFILE",
shots: 1024,
circuit: { num_qubits: 1, operations: [{ gate: "h", target: 0 }] },
});
Useful methods
-
health, portfolio, echoTypes, runGate, runCircuit, transformText
-
listBackends, transpile, importQasm, exportQasm
-
submitCircuitJob, getCircuitJob, getCircuitJobResult, cancelCircuitJob
Troubleshooting
-
Catch QuantumApiError and inspect status, code, requestId, and details.
-
If a protected runtime call returns 401, check the supplied API key or your backend proxy.
-
Keep API keys and IBM tokens on a server when distributing an application to other people.
Feedback, contributions, comments, and questions
Questions, corrections, and issue reports are welcome. Email MrDJ@DavidJGrimsley.com or open an issue at github.com/davidjgrimsley/quantum-api/issues.
Install the Quantum API skill
Add the agent skill when you want coding assistants to find the Quantum API guides and integration notes quickly.
Agent version (.md)
Coding agents can use the plain Markdown companion for this guide at /public-facing/api/quantum/typescript-sdk.md.