Digital Twin QPU — API Reference

curl — submit a job

export BASE="http://localhost/api/v1/digital-twin"
export TOKEN="YOUR_ACCESS_TOKEN"

# Submit a Bell-state circuit (QASM string)
curl -s -X POST "$BASE/jobs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "backend_id": "ibm_jakarta_like",
    "circuits": ["OPENQASM 2.0; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;"],
    "shots": 1024
  }'

# Poll job status
curl -s "$BASE/jobs/JOB_ID" -H "Authorization: Bearer $TOKEN"

# Get results
curl -s "$BASE/jobs/JOB_ID/result" -H "Authorization: Bearer $TOKEN"

Python (requests)

import requests, time

BASE = "http://localhost/api/v1/digital-twin"
headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}

# Submit job
r = requests.post(f"{BASE}/jobs", headers=headers, json={
    "backend_id": "ibm_jakarta_like",
    "circuits": ['OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;'],
    "shots": 1024,
})
job_id = r.json()["job_id"]
print("Submitted:", job_id)

# Poll until done
while True:
    status = requests.get(f"{BASE}/jobs/{job_id}", headers=headers).json()
    print("Status:", status["status"])
    if status["status"] in ("COMPLETED", "FAILED", "CANCELLED"):
        break
    time.sleep(1)

# Get counts
result = requests.get(f"{BASE}/jobs/{job_id}/result", headers=headers).json()
print("Counts:", result["results"][0]["counts"])

TypeScript / Node (fetch)

const BASE = "http://localhost/api/v1/digital-twin";
const headers = {
  "Authorization": `Bearer ${ACCESS_TOKEN}`,
  "Content-Type": "application/json",
};

// Submit job
const res = await fetch(`${BASE}/jobs`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    backend_id: "ibm_jakarta_like",
    circuits: ['OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;'],
    shots: 1024,
  }),
});
const { job_id } = await res.json();

// Poll
let status;
do {
  await new Promise(r => setTimeout(r, 1000));
  status = await (await fetch(`${BASE}/jobs/${job_id}`, { headers })).json();
} while (!["COMPLETED","FAILED","CANCELLED"].includes(status.status));

const result = await (await fetch(`${BASE}/jobs/${job_id}/result`, { headers })).json();
console.log(result.results[0].counts);

Java (HttpClient)

var client = HttpClient.newHttpClient();
var headers = new String[]{"Authorization","Bearer "+ACCESS_TOKEN,"Content-Type","application/json"};
String base = "http://localhost/api/v1/digital-twin";

// Submit
var body = """{"backend_id":"ibm_jakarta_like","circuits":["OPENQASM 2.0; ..."],"shots":1024}""";
var req = HttpRequest.newBuilder()
    .uri(URI.create(base + "/jobs"))
    .headers(headers)
    .POST(BodyPublishers.ofString(body))
    .build();
var resp = client.send(req, BodyHandlers.ofString());
System.out.println(resp.body());

Postman

• Create a collection variable ACCESS_TOKEN
• Add a pre-request script to auto-login and set ACCESS_TOKEN
• On each request: Headers → Authorization: Bearer <ACCESS_TOKEN> (use Postman's collection variable in double-curly notation)
• Import the OpenAPI spec from /api/v1/digital-twin/openapi.json