Quantum API TypeScript SDK
The TypeScript SDK is a package-ready Node.js client for the Quantum API. It normalizes the mounted API address for you and provides typed methods for runtime calls, account setup, IBM profiles, and jobs.
Runtime / package
Node.js package
Version
0.1.2
What this SDK is
@mr.dj2u/quantum-api is a TypeScript client for Node.js applications. It exposes named methods instead of making you build every URL and header yourself.
Install
npm install @mr.dj2u/quantum-api
Use Node.js 18 or later. The package supports ESM and CommonJS consumers.
Configure
The base URL is the web address the SDK sends requests to. Give the client either the mounted Quantum API address or the same address ending in /v1; the SDK normalizes it.
import { QuantumApiClient } from "@mr.dj2u/quantum-api";
const runtimeApiKey = "<your-runtime-api-key>";
const client = new QuantumApiClient({
baseUrl: "https://davidjgrimsley.com/public-facing/api/quantum",
apiKey: runtimeApiKey,
});
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.
Bearer token
Account key management and IBM profile methods use the signed-in user's bearer token.
Per-call override
Pass auth options to a method only when that call needs different credentials.
IBM profiles and jobs
Use bearer-authenticated profile methods to create, verify, update, and remove an IBM profile. Then submit a circuit, QASM, or random job with the saved profile name and poll the job result.
IBM hardware jobs have to wait in a queue before starting; get started at quantum.cloud.ibm.com.
const job = await client.submitCircuitJob({
provider: "ibm",
backend_name: "ibm_brisbane",
ibm_profile: "my-profile",
shots: 1024,
circuit: { num_qubits: 1, operations: [{ gate: "h", target: 0 }] },
});
Useful methods
-
health, portfolio, echoTypes, runGate, runCircuit, transformText
-
listBackends, transpile, importQasm, exportQasm, runQasm
-
listKeys, createKey, revokeKey, rotateKey, deleteKey
-
listIbmProfiles, createIbmProfile, updateIbmProfile, verifyIbmProfile, deleteIbmProfile
-
submitCircuitJob, submitQasmJob, submitRandomJob, getCircuitJob, getCircuitJobResult, cancelCircuitJob
Troubleshooting
-
Catch QuantumApiError and inspect statusCode, code, requestId, and details.
-
If a runtime call returns 401, check the API key. If a profile call returns 401, check the bearer token.
-
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 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/typescript-sdk.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.