API & SDK Developer User Guide | Ojanvu Quantum Cloud

1 Architecture & Physical Hardware Interface

Ojanvu provides direct programmatic access to continuous-variable physical optical quantum processors (QPUs). When you submit a circuit through the API or official Python SDK, your OpenQASM program is compiled into optical beamline pulse sequences and executed directly on the physical hardware cluster at Ojanvu Quantum Labs.

Unlike conventional quantum simulators or mock harnesses, all job requests are executed on genuine optical nodes with true quantum state preparation, beam manipulation, and physical measurement readout.

Physical Hardware Node Target

The active production hardware node is designated Testing 1. All jobs route directly to this physical optical beamline.

2 Step 1: Requesting and Managing Your API Key

To maintain rigorous access governance and guarantee deterministic optical beamline time for mission-critical enterprise workloads, API keys are not granted by default. Users follow a managed cryptographic allocation workflow:

Step 1.1: Sign in to your account at cloud.ojanvu.com.
Step 1.2: Navigate to the API & SDK tab from the navigation header.
Step 1.3: Complete the Request Enterprise API Key ticket with your Organization Name, Enterprise Workload Domain (e.g., Pharmaceutical Drug Discovery, CI/CD Pipeline Verification, Quantitative Finance), and a brief workflow abstract.
Step 1.4: Ojanvu evaluates the request and approves the access, issuing your dedicated bearer key (format: oj_live_...). Once approved, your active key appears immediately on your dashboard.
Step 1.5: You can safely reveal, copy, or rotate the key at any time. Rotating immediately revokes access for deprecated instances.

Security Best Practice

Treat your API key as a confidential credential. Never commit it to public version control repositories. Use environment variables such as OJANVU_API_KEY in production workflows.

3 Step 2: Preparing OpenQASM Circuits

Ojanvu natively supports standard OpenQASM 2.0 and OpenQASM 3.0 circuit specifications. The physical optical compiler automatically performs register allocation, gate decomposition, and measurement mapping.

Standard supported gates include:

Single-Qubit Superposition: h q[0]; (Hadamard gate)
Pauli Operations: x q[0];, y q[0];, z q[0];
Two-Qubit Entanglement: cx q[0], q[1]; (Controlled-NOT / CNOT), cz q[0], q[1];
Continuous Rotations: rx(theta) q[0];, ry(theta) q[0];, rz(theta) q[0];
Measurement: measure q -> c; or measure q[0] -> c[0];

BELL-STATE.QASM · OPENQASM 2.0 CANONICAL CIRCUIT

OPENQASM 2.0;
include "qelib1.inc";

qreg q[2];
creg c[2];

// Generate maximally entangled Bell state (|00> + |11>) / sqrt(2)
h q[0];
cx q[0], q[1];

// Measure quantum registers into classical bits
measure q -> c;

4 Step 3: Dispatching via the Official Python SDK

The official Python client library provides high-level abstractions for job submission, automated hardware polling, shot histogram extraction, and error handling.

INSTALLATION · TERMINAL

pip install ojanvu

PYTHON 3.9+ · SYNCHRONOUS AND ASYNC DISPATCH

from ojanvu import Client

# 1. Initialize client with authorized key and endpoint
client = Client(
    api_key="oj_live_fadf9682c4ae4650a5508f77bfa3f911",
    api_url="https://api.ojanvu.com",
    device="Testing 1"
)

# 2. OpenQASM circuit
qasm_str = """
OPENQASM 2.0;
include "qelib1.inc";

qreg q[2];
creg c[2];

h q[0];
cx q[0], q[1];
measure q -> c;
"""

# 3. Submit circuit to physical hardware node
job = client.run(
    circuit=qasm_str,
    shots=1000,
    name="Enterprise-VQE-Verification"
)
print(f"[✓] Circuit Enqueued. Job ID: {job.id}")

# 4. Wait for hardware completion (blocks until physical readout finishes)
result = job.result(timeout_sec=30)

print(f"[✓] Completed in {result.execution_time:.3f} seconds")
print(f"Empirical Probabilities: {result.get_probabilities()}")
print(f"Raw Physical Counts:     {result.counts}")
# Example Output: {'00': 514, '11': 486}

5 Step 4: Submitting via Standard REST API (cURL)

Any programming language or framework capable of issuing HTTP requests can integrate with Ojanvu via our standard REST endpoints. Authenticate using the X-API-Key: <YOUR_API_KEY> or Authorization: Bearer <YOUR_API_KEY> header.

CURL · DISPATCH CIRCUIT TO HARDWARE (POST /v1/jobs)

curl -X POST https://api.ojanvu.com/v1/jobs \
  -H "Content-Type: application/json" \
  -H "X-API-Key: oj_live_fadf9682c4ae4650a5508f77bfa3f911" \
  -d '{
    "name": "Automated-Pipeline-Execution",
    "circuit": "OPENQASM 2.0;\ninclude \"qelib1.inc\";\nqreg q[2];\ncreg c[2];\nh q[0];\ncx q[0], q[1];\nmeasure q -> c;\n",
    "shots": 1000,
    "device_id": "Testing 1"
  }'

Expected Response (HTTP 200 OK):

JSON RESPONSE · SUBMISSION RECEIPT

{
  "job_id": "oj_job_cf74bcce578f4d45",
  "status": "QUEUED",
  "target_device": "Testing 1",
  "shots": 1000,
  "created_at": "2026-11-09 17:15:17"
}

To poll the job status and retrieve physical measurement distributions:

CURL · QUERY JOB TELEMETRY (GET /v1/jobs/{job_id})

curl -X GET https://api.ojanvu.com/v1/jobs/oj_job_cf74bcce578f4d45 \
  -H "X-API-Key: oj_live_fadf9682c4ae4650a5508f77bfa3f911"

6 Step 5: Node.js & TypeScript Integration

Integrate quantum execution into modern serverless backends, edge functions, or Node.js services:

JAVASCRIPT / TYPESCRIPT · ASYNCHRONOUS POLLING PIPELINE

const API_BASE = "https://api.ojanvu.com";
const API_KEY = "oj_live_fadf9682c4ae4650a5508f77bfa3f911";

async function executeCircuit() {
  const qasm = `OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0], q[1];
measure q -> c;`;

  // 1. Submit job
  const res = await fetch(`${API_BASE}/v1/jobs`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY
    },
    body: JSON.stringify({
      name: "Node-Cloud-Pipeline",
      circuit: qasm,
      shots: 1000,
      device_id: "Testing 1"
    })
  });
  const { job_id } = await res.json();
  console.log(`[✓] Circuit enqueued: ${job_id}`);

  // 2. Poll until physical execution completes
  let completed = false;
  while (!completed) {
    await new Promise(r => setTimeout(r, 750));
    const poll = await fetch(`${API_BASE}/v1/jobs/${job_id}`, {
      headers: { "X-API-Key": API_KEY }
    });
    const job = await poll.json();
    if (job.status === "COMPLETED") {
      console.log(`[✓] Execution finished in ${job.execution_time}s`);
      console.log("Probabilities:", job.counts);
      completed = true;
    }
  }
}

executeCircuit();

7 Step 6: Telemetry, Timestamps & Measurement Payloads

Every completed job includes full audit trail telemetry, exact timestamps, and physical measurement readout:

Field	Type	Description
`job_id`	String	Unique cryptographic identifier (e.g. `oj_job_cf74bcce578f4d45`).
`status`	String	Execution state: `QUEUED`, `RUNNING`, `COMPLETED`, or `FAILED`.
`counts`	Object	Measurement histogram mapping computational basis states to observed shot counts (e.g. `{"00": 514, "11": 486}`).
`execution_time`	Float	Active hardware beamline dwell time in seconds (e.g. `8.970`).
`created_at`	Timestamp	Submission receipt timestamp recorded by central API.
`leased_at`	Timestamp	Hardware acquisition timestamp when physical optical beam was engaged.
`completed_at`	Timestamp	Hardware readout confirmation timestamp.
`raw_result`	String	Direct physical serial readout telemetry from the QPU node (e.g. `00=520; 11=480; STATUS=OK`).

8 Step 7: External CI/CD Pipelines & Workflows

Ensure algorithms, quantum compilers, and variational ansatzes never regress by adding physical hardware tests to your continuous integration suites.

GITHUB ACTIONS WORKFLOW · .github/workflows/quantum-hardware-ci.yml

name: Quantum Physical Hardware Regression Suite

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  verify-qpu-execution:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'

      - name: Install Ojanvu Quantum SDK
        run: pip install ojanvu pytest

      - name: Run Circuit Integration on Optical QPU
        env:
          OJANVU_API_KEY: ${{ secrets.OJANVU_API_KEY }}
        run: |
          python -c "
          from ojanvu import Client
          import os
          client = Client(api_key=os.environ['OJANVU_API_KEY'], api_url='http://api.ojanvu.com')
          job = client.run(circuit='OPENQASM 2.0; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0], q[1]; measure q -> c;', shots=1000)
          res = job.result(timeout_sec=45)
          probs = res.get_probabilities()
          # Verify Bell state entanglement fidelity threshold
          assert probs.get('00', 0) > 0.40 and probs.get('11', 0) > 0.40, 'Bell state fidelity below tolerance'
          print('[✓] Physical QPU verification passed successfully!')
          "

9 Step 8: Error Codes, Rate Limits & SLA

The Ojanvu API returns standard HTTP status codes. When an error occurs, the response body includes a JSON object with a detailed detail message.

Status Code	Condition	Remediation Step
`401 Unauthorized`	Missing or invalid API key.	Check that your request includes the `X-API-Key: <key>` header and that the key is approved.
`403 Forbidden`	Key revoked or insufficient quota.	Visit your User Profile page to check remaining shot quota balance or request an increase.
`422 Unprocessable`	OpenQASM syntax error.	Validate your OpenQASM program structure, qubit allocation, and gate definitions in the web compiler.
`429 Too Many Requests`	Exceeded 120 req / minute rate limit.	Implement exponential backoff and jitter in your external client dispatch loop.
`503 Unavailable`	Target hardware offline.	Target hardware is undergoing optical laser re-calibration. Check `/v1/devices` status.

Ojanvu Quantum API & SDK Developer Guide