Quantum

Quantum REST API

All quantum solvers are accessible through a single endpoint. Local simulation is the default substrate. Switch to IBM Eagle hardware by changing one parameter.

POST /api/solve

Submit a single optimization problem to a quantum solver. The response includes the optimal solution, cost metric, solver metadata, and timing breakdown.

Request body

Example — QAOA route optimization

curl http://localhost:11435/api/solve \
  -H "Content-Type: application/json" \
  -d '{
    "solver": "qaoa",
    "problem": {
      "type": "route_optimization",
      "nodes": [
        {"id": "depot", "lat": 40.7128, "lng": -74.0060},
        {"id": "a", "lat": 40.7580, "lng": -73.9855},
        {"id": "b", "lat": 40.7484, "lng": -73.9857},
        {"id": "c", "lat": 40.7614, "lng": -73.9776}
      ],
      "constraints": {"max_distance_km": 50, "vehicle_count": 1}
    },
    "substrate": "local",
    "shots": 1024
  }'

Response

{
  "id": "qj_01HZ3X...",
  "solver": "qaoa",
  "substrate": "local",
  "status": "completed",
  "solution": {
    "route": ["depot", "c", "a", "b", "depot"],
    "cost": 12.4,
    "unit": "km"
  },
  "meta": {
    "shots": 1024,
    "optimal_count": 847,
    "energy": -3.72,
    "depth": 4,
    "elapsed_ms": 230
  }
}

POST /api/solve/batch

Submit up to 10 problems in a single request. Each problem is solved independently and results are returned in the same order. Batch requests are processed in parallel on local substrate and queued on IBM Eagle.

Request body

Example — batch route optimization

import requests

response = requests.post("http://localhost:11435/api/solve/batch", json={
    "solver": "qaoa",
    "problems": [
        {
            "type": "route_optimization",
            "nodes": [
                {"id": "depot", "lat": 40.7128, "lng": -74.0060},
                {"id": "a", "lat": 40.7580, "lng": -73.9855}
            ],
            "constraints": {"max_distance_km": 25, "vehicle_count": 1}
        },
        {
            "type": "route_optimization",
            "nodes": [
                {"id": "depot", "lat": 34.0522, "lng": -118.2437},
                {"id": "x", "lat": 34.0195, "lng": -118.4912}
            ],
            "constraints": {"max_distance_km": 40, "vehicle_count": 1}
        }
    ],
    "substrate": "local",
    "shots": 2048
})

results = response.json()["results"]
for r in results:
    print(r["solution"]["route"], r["solution"]["cost"])

Batch response

{
  "id": "qb_01HZ3X...",
  "solver": "qaoa",
  "substrate": "local",
  "status": "completed",
  "results": [
    {
      "index": 0,
      "status": "completed",
      "solution": {"route": ["depot", "a", "depot"], "cost": 5.2, "unit": "km"},
      "meta": {"shots": 2048, "optimal_count": 1893, "energy": -1.88, "depth": 2, "elapsed_ms": 85}
    },
    {
      "index": 1,
      "status": "completed",
      "solution": {"route": ["depot", "x", "depot"], "cost": 22.7, "unit": "km"},
      "meta": {"shots": 2048, "optimal_count": 1756, "energy": -2.14, "depth": 2, "elapsed_ms": 91}
    }
  ],
  "total_elapsed_ms": 176
}

Error codes

Substrates