API Quick Reference

Last Updated: October 31, 2025

Base URL

Production: https://api.qsurf.ai Local Dev: http://localhost:8080

Authentication

• Public endpoints: No auth required
• GA validation: Test account only (email in request)
• Rate limits: 5 validations/day (beta tier)

Quick Endpoints

Health Check

GET /api/v1/health

FTQC Standard Validation (7 metrics)

curl -X POST https://api.qsurf.ai/api/v1/ftqc_standard_validation \
  -F "syndromes_d3=@d3_detection_events.b8" \
  -F "syndromes_d5=@d5_detection_events.b8" \
  -F "syndromes_d7=@d7_detection_events.b8" \
  -F "platform=google_willow" \
  -F "rounds=10"

Hardware Quality

curl -X POST https://api.qsurf.ai/api/v1/hardware_quality \
  -F "file=@detection_events.b8" \
  -F "platform=google_willow" \
  -F "distance=7" \
  -F "rounds=50"

GA Validation (Test Account Only)

curl -X POST https://api.qsurf.ai/api/v1/ga_validation \
  -F "syndromes=@detection_events.b8" \
  -F "platform=google_willow" \
  -F "distance=7" \
  -F "rounds=50"

Hypothesis Discovery (Sprint 12 - Scientific Defensibility)

# Basic request (Free tier - edge detection + multi-criteria)
curl -X POST https://api.qsurf.ai/api/v1/analyze/discover-hypothesis \
  -H "Content-Type: application/json" \
  -d '{
    "data": [[1.2, 3.4, ...], ...],
    "enable_edge_detection": true,
    "enable_multi_criteria": true,
    "criteria": ["mdl", "bic", "aic"]
  }'

# Full validation (Premium tier - includes bootstrap stability)
curl -X POST https://api.qsurf.ai/api/v1/analyze/discover-hypothesis \
  -H "Content-Type: application/json" \
  -d '{
    "data": [[1.2, 3.4, ...], ...],
    "enable_edge_detection": true,
    "enable_multi_criteria": true,
    "criteria": ["mdl", "bic", "aic"],
    "enable_bootstrap": true,
    "bootstrap_samples": 20
  }'

# Health check
GET /api/v1/analyze/discover-hypothesis/health

Key Parameters: - enable_edge_detection (bool, default: true) - Condition number & rank checks (~2ms) - enable_multi_criteria (bool, default: false) - MDL/BIC/AIC consensus (~5ms) - criteria (list, default: ["mdl", "bic", "aic"]) - Which criteria to use - enable_bootstrap (bool, default: false, Premium only) - Stability validation (~500ms) - bootstrap_samples (int, default: 20) - Number of bootstrap iterations

Tier Restrictions: - Free: Edge detection + multi-criteria evaluation - Premium: All features including bootstrap stability testing

Response Fields: - suggestions[]: Ranked hypothesis candidates with scores - metadata.edge_detection: Numerical stability checks - metadata.multi_criteria: Criterion agreement analysis - metadata.bootstrap_stability: Resampling validation (Premium only)

List Platforms

GET /api/v1/platforms
GET /api/v1/platforms/google_willow

Single Validation (Legacy)

curl -X POST https://api.qsurf.ai/api/v1/validate \
  -F "file=@detection_events.b8" \
  -F "platform=google_willow" \
  -F "distance=3" \
  -F "rounds=10"

Response Codes

• 200: Success
• 400: Bad request (invalid parameters)
• 404: Not found
• 413: File too large
• 429: Rate limit exceeded
• 500: Server error

Key Metrics Explained

Pre-Decoder Observable Flip Ratio (ρ_obs)

• Range: 0 to 1 (typically 0.6-0.9 for sub-threshold)
• Interpretation: < 1.0 = observable flips increase with distance (good)
• NOT Google's post-decoder Λ (different metric)

R² Linearity

• Range: 0 to 1
• Threshold: > 0.999 = Excellent
• Interpretation: How well Magnus expansion fits

Gate Fidelity

• Range: 0 to 1
• Threshold: > 0.999 for FTQC
• Grade: A (>99.97%), B (99.95-99.97%), C (99.90-99.95%)

Coherence Time

• Units: Microseconds (μs)
• Good: > 100 μs
• Excellent: > 1000 μs

Readout Fidelity

• Range: 0 to 1
• Threshold: > 0.95 acceptable, > 0.99 excellent
• Common limiting factor: Often 85-92%

Sprint 12: Scientific Defensibility Features

Layer 0: Data Quality Firewall (v1.2.1)

🎯 Why This Matters (ELI5):

Imagine trying to tune a guitar by only knowing if each string is "too high" or "too low" (binary data). You can't tell HOW MUCH to adjust - you need the actual pitch values (continuous data).

The Problem: Quantum error correction systems output two types of data:

• Binary syndromes (0s and 1s): "Did an error happen?" → Good for error correction, but lacks frequency/phase information
• Soft syndromes (continuous values like 0.92, -1.3, 2.7): "How much did the signal deviate?" → Required for spectral mode analysis

What Layer 0 Does: Automatically detects when you accidentally send binary data to an analysis that needs continuous values. Instead of wasting 30+ minutes on doomed calculations, it blocks the request in 20ms with a helpful error message explaining what data to request from your hardware provider.

How to Use It:

1. Just send your data - Layer 0 runs automatically
2. If you get HTTP 422 (BLOCK): Read the error message - it tells you exactly what's wrong and what to request
3. If you see WARN: Your data passed but has quality concerns - consider the warnings before trusting results
4. If you see PASS: Data quality is good, proceed with confidence! ✅

📖 Detailed Example: Read the Layer 0 blog post for the complete story of how binary syndrome data was the hidden problem that IT Gate missed.

Technical Details:

• Purpose: Catches binary syndrome data and low-quality inputs BEFORE expensive analysis
• Validation outcomes:
  • PASS (score ≥80): Data meets quality thresholds, proceed with analysis ✅
  • WARN (score 60-80): Data has quality concerns but analysis allowed ⚠️
  • BLOCK (score <60): Data quality too low, analysis rejected with HTTP 422 🚨
• Key Checks:
  • Entropy thresholds: Binary data has ~1 bit/detector (fails spectral mode analysis)
  • Dynamic range: Quantized data (<10 unique values) triggers warnings
  • Spectral flatness: Detects over-smoothed/preprocessed data (SFM < 0.2)
  • Temporal coherence: Mutual information check for adjacent time-steps
  • Metadata completeness: Validates provenance, data type, phase information
• Configuration presets:
  • strict: Production use (entropy ≥5.0 bits, score ≥85)
  • balanced (default): General use (entropy ≥4.0 bits, score ≥80)
  • permissive: Exploratory analysis (entropy ≥3.0 bits, score ≥70)
• Overhead: 19.6ms average (25ms budget)
• Integration: Automatically runs before hypothesis discovery when enable_layer0=true
• Error codes:
  • HTTP 422: Data quality blocked (BLOCK status)
  • HTTP 413: Input size exceeds limits (1M rows, 10K cols, 1GB)
• Real-world impact: 98.4% reduction in wasted computation, 89% reduction in support tickets
• Educational errors: Actionable messages guide users to request pre-threshold soft syndrome data

Example error message (binary data detected):

{
  "error": "LAYER0_BLOCK",
  "blocked_reason": "Binary syndrome data detected (2 unique values)",
  "recommendation": "Request pre-threshold soft syndrome data from hardware provider",
  "educational_note": "Spectral mode analysis requires continuous detector values..."
}

Layer 1: Edge Case Detection

• Condition Number: > 10⁶ = warning, > 10¹⁰ = critical (BLOCKS analysis)
• Rank Deficiency: Detects when data has fewer degrees of freedom than expected
• Purpose: Catches numerically unstable data BEFORE model selection
• Overhead: ~2ms (always recommended)

Layer 2: Multi-Criteria Evaluation

• MDL (Minimum Description Length): Prefers simpler models, good for avoiding overfitting
• BIC (Bayesian Information Criterion): Strong simplicity penalty, best for large samples
• AIC (Akaike Information Criterion): Weaker penalty, better for small samples/prediction
• Agreement Levels:
• High (all 3 agree): Model choice is robust ✅
• Moderate (2 of 3): Reasonable but double-check ⚠️
• Low (all disagree): RED FLAG - investigate further 🚨
• Purpose: Eliminates single-metric bias
• Overhead: ~5ms

Layer 3: Bootstrap Stability (Premium Only)

• Variance Ratio Thresholds:
• < 0.05: Stable (result robust to sampling noise) ✅
• 0.05 - 0.15: Moderate (some sensitivity) ⚠️

• 0.15: Unstable (highly sample-dependent) 🚨

• Purpose: Validates model selection will replicate on new data
• Overhead: ~500ms for 20 bootstrap samples
• When to use: Final validation before publication/critical decisions

Countering AI-Driven Overconfidence

Sprint 12 addresses the "Illusion of Competence" problem where researchers trust automated model selection without validation. Read more: https://storage.googleapis.com/getqore-validation-data/blog/scientific-defensibility-hypothesis-discovery.html

File Formats

B8 (Google Willow)

• Binary packed bits (little-endian)
• Requires: distance, rounds parameters

NumPy (.npy)

• Shape: (n_shots, n_cycles, n_detectors)

CSV

• Simple text format
• One row per shot

Common Parameters

• platform: google_willow, stim, ibm_heron, ionq_forte
• distance: 3, 5, 7 (surface code distance)
• rounds: Number of QEC cycles (10-50 typical)
• n_shots: Number of measurements (10K-50K typical)

Complete API Documentation

See: README.md in qcore_context/ or prod_v1/

Home | Blog | Contact Support