API Documentation

Complete reference for the XCTP quantum circuit emulation API. Version 2.0.

Overview

The XCTP API provides quantum circuit emulation over REST. Submit quantum circuits as JSON or OpenQASM 2.0, choose your execution engine, receive measurement results. No quantum hardware required.

Base URL: https://involvedinvolutions.com/api

Quick Start

1. Sign up for an API key

curl -X POST https://involvedinvolutions.com/api/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

# Response: {"api_key": "xctp-abc123...", "tier": "free", ...}

2. Run a Bell state circuit

curl -X POST https://involvedinvolutions.com/api/v1/run \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "xctp-YOUR-KEY-HERE",
    "num_qubits": 2,
    "gates": [
      {"gate": "h", "target": 0},
      {"gate": "cx", "control": 0, "target": 1}
    ],
    "shots": 1024
  }'

3. Or use OpenQASM 2.0

curl -X POST https://involvedinvolutions.com/api/v1/run-qasm \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "xctp-YOUR-KEY-HERE",
    "qasm": "OPENQASM 2.0;\ninclude \"qelib1.inc\";\nqreg q[2];\nh q[0];\ncx q[0],q[1];",
    "shots": 1024
  }'

Python

import requests

# Sign up
key = requests.post("https://involvedinvolutions.com/api/v1/signup",
    json={"email": "you@example.com"}).json()["api_key"]

# Run circuit
resp = requests.post("https://involvedinvolutions.com/api/v1/run", json={
    "api_key": key,
    "num_qubits": 2,
    "gates": [
        {"gate": "h", "target": 0},
        {"gate": "cx", "control": 0, "target": 1}
    ],
    "shots": 1024
})

data = resp.json()
print(f"Status: {data['status']}")
print(f"Counts: {data['counts']}")
print(f"Time:   {data['execution_time_ms']}ms")

Authentication

An API key is required for all circuit execution endpoints. Get one via /api/v1/signup.

Pass your key in the request body as api_key:

{"api_key": "xctp-your-key-here", "num_qubits": 2, ...}

For account and usage endpoints, use the Authorization header:

Authorization: Bearer xctp-your-key-here

POST /api/v1/signup

Create a free account. Returns an API key with 60 seconds of free compute.

Field	Type	Required	Description
`email`	string	Yes	Valid email address
`name`	string	No	Your name (max 200 chars)
`company`	string	No	Company name (max 200 chars)

// Response
{
  "api_key": "xctp-a1b2c3d4e5f6...",
  "tier": "free",
  "email": "you@example.com",
  "message": "Account created. 60s free compute."
}

Health Check

GET /api/health

Returns engine status. No authentication required.

{
  "status": "operational",
  "engine": "XCTP",
  "version": "2.0.0",
  "max_qubits": 50000
}

List Engines

GET /api/v1/engines

Returns available execution engines and their descriptions.

{
  "engines": {
    "auto":   "Automatic dispatch (SparseQPU ≤50q, CNTA >50q)",
    "sparse": "SparseQPU — true statevector, exact amplitudes, ≤50 qubits",
    "cnta":   "CNTA — O(N) geometric, 1–50,000 qubits",
    "tee":    "TEE v1 — legacy emulator"
  }
}

Run Circuit (Synchronous)

POST /api/v1/run

Execute a circuit and return results immediately.

Request Body

Field	Type	Required	Description
`api_key`	string	Yes	Your API key
`num_qubits`	integer	Yes	1 to 50,000
`gates`	array	Yes	Ordered gate operations
`shots`	integer	No	1 to 100,000 (default: 1024)
`engine`	string	No	"auto" (default), "sparse", "cnta", or "tee"

Gate Object

Field	Type	Description
`gate`	string	Gate name (see Supported Gates)
`target`	integer	Target qubit index
`control`	integer	Control qubit (for cx, cz, cp, ccx)
`control2`	integer	Second control (for ccx/Toffoli)
`target2`	integer	Second target (for swap)
`angle`	float	Rotation angle in radians (for rx, ry, rz, p, cp)

Response

{
  "job_id": "a1b2c3d4-...",
  "status": "COMPLETED",
  "counts": {"00": 512, "11": 512},
  "num_qubits": 2,
  "total_shots": 1024,
  "execution_time_ms": 0.42,
  "backend": "xctp-v2",
  "engine_version": "XCTP-2.0",
  "tier": "free",
  "trial_remaining_sec": 49.5
}

Submit Job (Async)

POST /api/v1/jobs

Submit a circuit for background execution. Returns immediately with a job ID. Poll /api/v1/jobs/{id} for results.

Same request body as /api/v1/run.

// Response
{
  "job_id": "a1b2c3d4-...",
  "status": "QUEUED",
  "message": "Accepted: 10000q circuit, 2 gates, 10 shots"
}

Get Job Result

GET /api/v1/jobs/{job_id}

Retrieve results for a submitted job. Only the original submitter can access results (verified by API key or IP).

Pass your API key via header: Authorization: Bearer xctp-...

Run OpenQASM Circuit

POST /api/v1/run-qasm

Execute a circuit from an OpenQASM 2.0 string. Qiskit users: pass qc.qasm() directly.

Field	Type	Required	Description
`api_key`	string	Yes	Your API key
`qasm`	string	Yes	OpenQASM 2.0 circuit string
`shots`	integer	No	1 to 100,000 (default: 1024)
`engine`	string	No	"auto", "sparse", "cnta", or "tee"

// Example: Qiskit integration
from qiskit import QuantumCircuit
import requests

qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)

resp = requests.post("https://involvedinvolutions.com/api/v1/run-qasm", json={
    "api_key": "xctp-YOUR-KEY",
    "qasm": qc.qasm(),
    "shots": 1024
}).json()

print(resp["counts"])  # {"00": 512, "11": 512}

Check Usage

GET /api/v1/usage

Check your account usage and remaining compute. Requires Authorization: Bearer header.

{
  "tier": "free",
  "used_sec": 10.5,
  "remaining_sec": 49.5,
  "max_qubits": 50
}

Supported Gates (22)

Gate	Name	Parameters	Description
`h`	Hadamard	target	Creates equal superposition
`x`	Pauli-X	target	Bit flip
`y`	Pauli-Y	target	Bit + phase flip
`z`	Pauli-Z	target	Phase flip
`s`	S gate	target	π/2 phase
`t`	T gate	target	π/4 phase
`sdg`	S†	target	Inverse S gate
`tdg`	T†	target	Inverse T gate
`id`	Identity	target	No-op (identity gate)
`barrier`	Barrier	-	Optimization barrier
`rx`	Rx	target, angle	X-axis rotation
`ry`	Ry	target, angle	Y-axis rotation
`rz`	Rz	target, angle	Z-axis rotation
`p`	Phase	target, angle	Phase gate (alias: u1)
`u2`	U2	target, angle	Single-qubit U2 rotation
`u3`	U3	target, angle	General single-qubit rotation
`cx`	CNOT	control, target	Controlled NOT
`cz`	CZ	control, target	Controlled Z
`cp`	CPhase	control, target, angle	Controlled phase
`swap`	SWAP	target, target2	Swap two qubits
`ccx`	Toffoli	control, control2, target	Controlled-controlled NOT
`qft`	QFT	-	Quantum Fourier Transform (whole register)

Engine Selection

Pass "engine" in your request to choose an execution backend:

Engine	Best For	Description
`auto`	Most users	Automatic: SparseQPU for ≤50q or rotation gates, CNTA for >50q Clifford
`sparse`	Exact results ≤50q	True statevector simulator with complex amplitudes. Exact Born rule probabilities.
`cnta`	Large circuits	O(N) geometric emulator. Scales to 50,000 qubits. HH=I correct.
`tee`	Legacy comparison	Original toral entanglement emulator. Known HH≠I bug above 50 qubits.

Tip: Use "engine": "auto" (or omit the field) for best results. Force an engine only when testing or comparing.

Scaling Characteristics

Qubits	Memory	Time (CNTA)
10	<1 KB	<0.1ms
100	~10 KB	~0.1ms
1,000	~100 KB	~15ms
5,000	~500 KB	~100ms
10,000	~1 MB	~400ms
50,000	~5 MB	~5s

Memory scales linearly O(N). Standard quantum simulators require O(2^N) memory, making circuits above ~40 qubits infeasible.