Quantum API Developer Documentation

Reference for the Upcube Quantum API v1. All endpoints are served from the Next.js App Router under /api/quantum/v1/.

Authentication not yet active. All API endpoints currently return 401 Unauthorized because API key authentication requires a user auth system and server-side database, which are not yet present. The endpoint routes exist in the codebase and enforce cost-safety gates, but cannot validate requests without auth. The examples below use a placeholder API key and show the intended request/response format once auth is enabled.

Quick Start

# Base URL (placeholder — production domain not yet assigned)
BASE="https://api.upcube.ai"   # not yet provisioned

# During local development, use:
# BASE="http://localhost:3000"

# API key (placeholder — real keys not yet available)
API_KEY="upcube_sk_placeholder_key_not_yet_generated"

# 1. List available templates
curl -s "$BASE/api/quantum/v1/templates" \
  -H "Authorization: Bearer $API_KEY" | jq .

# 2. Submit a bell-state job
curl -s -X POST "$BASE/api/quantum/v1/jobs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateId":"bell-state","shots":1024}' | jq .

# 3. Check job status
curl -s "$BASE/api/quantum/v1/jobs/{jobId}" \
  -H "Authorization: Bearer $API_KEY" | jq .

# 4. List recent jobs
curl -s "$BASE/api/quantum/v1/jobs?status=completed&limit=5" \
  -H "Authorization: Bearer $API_KEY" | jq .

# 5. List available backends
curl -s "$BASE/api/quantum/v1/backends" \
  -H "Authorization: Bearer $API_KEY" | jq .

Endpoints

POST/api/quantum/v1/jobs

Submit a quantum job to the local simulator. Jobs are executed synchronously on the local simulator and return results immediately.

Request Body

{
  "templateId": "bell-state",        // required - template identifier
  "shots": 1024,                     // required - number of measurement shots
  "backend": "local-simulator",      // optional - defaults to local-simulator
  "name": "My Bell State Run"        // optional - custom job name
}

Valid templateIds

quantum-coin-flip — 1-qubit superposition
bell-state — 2-qubit entanglement
grover-search — 3-qubit simplified Grover
qaoa-optimization — 4-qubit simplified QAOA
quantum-randomness — 4-qubit randomness

Cost-safety Gates

Shots are capped at maxShotsPerRun (default 10,000).
When costSafeMode is enabled, only local-simulator is available.
When disableRealHardware is on, QPU backends are blocked.
AWS Braket backends return errors until AWS credentials are configured.

Response (201)

{
  "task": {
    "id": "api-1716998400000-abc123",
    "name": "Bell State Entanglement",
    "templateId": "bell-state",
    "backend": "local-simulator",
    "shots": 1024,
    "status": "completed",
    "createdAt": "2026-05-20T12:00:00.000Z",
    "duration": "42ms",
    "costEstimate": "$0.00 (local simulator — API)",
    "result": {
      "counts": { "00": 512, "11": 512 },
      "histogram": [
        { "bitstring": "00", "probability": 0.5 },
        { "bitstring": "11", "probability": 0.5 }
      ],
      "circuitSnapshot": "Bell State (2 qubits, 4 gates)",
      "explanation": "## Bell State Entanglement ..."
    },
    "braketTaskArn": null
  },
  "warnings": []
}

GET/api/quantum/v1/jobs

List submitted jobs. Results are ordered by creation date (newest first).

Query Parameters

status — Filter by job status: completed, running, queued, failed, canceled, draft
limit — Maximum jobs to return (default 20, max 100)

Response (200)

{
  "tasks": [ ...QuantumTask[] ],
  "count": 5
}

GET/api/quantum/v1/jobs/:id

Get a single job by ID. Returns the full task object including result counts, histogram, and explanation when completed.

Response (200) — completed job

{
  "task": { ...QuantumTask }
}

Returns 404 if the job ID is not found.

GET/api/quantum/v1/backends

List available compute backends. Includes local simulators (always available, free), local QPU placeholder (offline), and AWS Braket QPU placeholders (not yet available).

Query Parameters

type — Filter: simulator or qpu

Response includes isAvailable and missingConfig fields per backend. QPU placeholders return isAvailable: false until AWS Braket is connected.

GET/api/quantum/v1/templates

List available quantum experiment templates with metadata, gate sequences, and sample results. Circuit objects are not serialized in API responses.

Query Parameters

category — Filter: Fundamentals, Entanglement, Algorithms
difficulty — Filter: Beginner, Intermediate, Advanced

Current Limitations

No authentication: All endpoints return 401. No auth provider or database is configured.
Simulator only: AWS Braket integration is a placeholder with no real SDK calls. QPU access is blocked by cost-safe mode and disableRealHardware flags.
No persistent task store: The task store uses browser localStorage. Server-side API endpoints cannot persist tasks across requests. Each API call creates a new in-memory task that is not saved.
No usage tracking: Usage metrics are placeholder data. No real per-key or per-user usage counters exist.
No rate limiting: No request rate limiting is implemented. This must be added before production use.
Placeholder domain: https://api.upcube.ai is used in docs examples only. This domain has not been provisioned or assigned.

Security Architecture (Planned)

Hashed storage: API keys will be hashed with SHA-256 before storage. Raw keys are never persisted or logged.
Server-only auth: API key validation runs exclusively on the server. Keys are never exposed to client-side JavaScript.
No credential exposure: AWS credentials, internal provider configs, and secrets are never returned in API responses.
Cost gates enforced: All API routes reuse the existing cost-safety and QPU restriction gates from lib/quantum/settings.ts.