--- name: Estimate then run a Quandela Quantum Toolbox algorithm description: >- Use Quandela Cloud's five pre-built quantum primitives (Chemistry VQE, Custom VQE, CVaR VQE, Graph DSI, Graph Isomorphism) without writing a photonic circuit — price the workload with the paired /estimate operation first, then submit, poll and collect results. api: openapi/quandela-quantum-toolbox-openapi.yml generated: '2026-08-17' method: generated source: >- openapi/_original/quandela-quantum-toolbox-openapi.json, openapi/_original/quandela-cloud-openapi.json, sandbox/quandela-sandbox.yml, errors/quandela-problem-types.yml, rate-limits/quandela-rate-limits.yml operations: - post_qt_chemistryvqe_estimate - post_qt_chemistryvqe - get_qt_chemistryvqe_by_job_id_status - get_qt_chemistryvqe_by_job_id_results - post_qt_customvqe_estimate - post_qt_customvqe - get_qt_customvqe_by_job_id_status - get_qt_customvqe_by_job_id_results - post_qt_cvarvqe_estimate - post_qt_cvarvqe - get_qt_cvarvqe_by_job_id_status - get_qt_cvarvqe_by_job_id_results - post_qt_graphDSI_estimate - post_qt_graphDSI - get_qt_graphDSI_by_job_id_status - get_qt_graphDSI_by_job_id_results - post_qt_graphIsomorphism_estimate - post_qt_graphIsomorphism - get_qt_graphIsomorphism_by_job_id_status - get_qt_graphIsomorphism_by_job_id_results - get_api_jobs_availability --- # Run a Quandela Quantum Toolbox algorithm Base URL: `https://api.cloud.quandela.com/` Auth: `Authorization: Bearer ` ## Why this surface, not `/api/jobs` `POST /api/jobs` takes an **opaque, SDK-serialised** photonic circuit — you effectively need `perceval-quandela` to build the body. The Quantum Toolbox (`/qt/*`) is the opposite: each algorithm has fully typed request, status, intermediate-result and result schemas in the OpenAPI, so **an agent can call it directly over HTTP with no SDK.** If a Toolbox primitive fits the problem, prefer it. ## The five algorithms Every one follows the identical four-operation shape at `/qt/`: | Algorithm | Path | Params schema | Results schema | |---|---|---|---| | Chemistry VQE | `/qt/chemistryvqe` | `ChemistryVqeParams` (contains `Atom[]`) | `ChemistryVqeResults` | | Custom VQE | `/qt/customvqe` | `CustomVqeParams` | `CustomVqeResults` | | CVaR VQE | `/qt/cvarvqe` | `CVarVqeParams` | `CVarVqeResults` | | Graph DSI (dense subgraph) | `/qt/graphDSI` | `GraphDSIParams` | `GraphDSIResults` | | Graph Isomorphism | `/qt/graphIsomorphism` | `GraphIsomorphismParams` | `GraphIsomorphismResults` | ## Step 1 — ALWAYS estimate first This is the one genuinely agent-friendly affordance on this API and you should never skip it. Each algorithm has a paired estimator that returns cost **without running anything and without spending credits**: ``` POST /qt//estimate Authorization: Bearer { ...same params as the real call... } ``` Returns `EstimationResult`: ``` { "nb_iterations": , "nb_shots_per_job": , "nb_total_shots": } ``` Use `nb_total_shots` as your budget gate. If it exceeds what you are authorised to spend, shrink the problem and estimate again — do not submit and hope. There is no equivalent estimator for arbitrary Perceval jobs, so this is a reason to stay on the Toolbox. ## Step 2 — Check your concurrency headroom Toolbox jobs have their **own** ceiling, separate from Perceval jobs: ``` GET /api/jobs/availability ``` Read `max_running_qt_jobs` and `num_running_qt_jobs`. Exceeding it returns `403 "Cannot have more than {MAX_QT_JOBS} running Quantum Toolbox jobs"` — note that this ceiling is a **403**, while the Perceval waiting-job ceiling is a **400**. There are no rate-limit headers to read. Also check platform status anonymously at `GET https://api.cloud.quandela.com/api/platforms/public` before committing. ## Step 3 — Submit ``` POST /qt/ Authorization: Bearer { ...params... } ``` Returns `QTJobId` → `{job_id}` (`job_id` is required in this schema, so it is always present). There is **no idempotency key** here either. A timed-out submit may or may not have created a job, and unlike `POST /api/jobs` the Toolbox has no `process_id` guard at all — so do not blind-retry. Poll instead: if you lost the `job_id`, you cannot recover it over REST (there is no job list endpoint), so persist the `job_id` the moment you receive it. ## Step 4 — Poll status ``` GET /qt//{job_id}/status ``` Returns `JobStatus`. The VQE algorithms additionally expose `IntermediateVqeResults`, so a status poll can carry the partial optimisation trace — useful for showing convergence, and for deciding to cancel early. Poll with exponential backoff; there is no `Retry-After` and no `429`. ## Step 5 — Collect results ``` GET /qt//{job_id}/results ``` Returns `JobResult` wrapping `Results`. ## Choosing an algorithm - **Chemistry VQE** — ground-state energy of a molecule. `ChemistryVqeParams` carries an `Atom[]` molecular specification. - **Custom VQE** — bring your own cost Hamiltonian / ansatz. - **CVaR VQE** — conditional-value-at-risk objective; the variant to reach for on combinatorial optimisation where you care about the tail. - **Graph DSI** — dense subgraph identification. - **Graph Isomorphism** — graph equivalence testing. ## Errors Same vendor envelope as the rest of the API: `{"detail": ..., "error": "..."}`, no machine-readable code, no RFC 9457. Toolbox-specific messages: | Status | `error` contains | Do | |---|---|---| | 403 | `Cannot have more than {MAX_QT_JOBS} running` | Wait for a running QT job to finish | | 403 | `No permission to use algorithm` | Your offer excludes it — escalate to a human | | 400 | `Quantum Toolbox command '{command}' is not defined` | Wrong algorithm name | | 400 | `Invalid iterator: must be a non-empty list` | Fix the params array | | 401 | `Invalid or expired job token` | Mint/reopen the job token | | 401 | `Not enough credits` | **Quota, not auth.** Stop; do not refresh the token | | 422 | validation | Read `detail..` | Remember: credit exhaustion arrives as `401`, so never treat `401` as a signal to refresh a credential without first reading the `error` string.