Building a Real-Time Drift Detection API

Welcome to Lesson 48 of the SNAP ADS Learning Hub! Lessons 46-47 have set up the deployment context — real-time topology and quantum-hardware integration. This lesson zooms in on a specific deployment surface: exposing ADACL as an API that other systems consume programmatically. The dashboard is the human interface; the API is the machine interface, and getting it right is what lets ADACL compose with the rest of an operational stack.

Whether you’re integrating ADACL with a custom monitoring portal, automating mitigations based on the score, or wiring it into a broader observability pipeline, the API contract is the boundary. This lesson covers the contract design choices, the request/response shape, the SLA discipline, and the versioning practices that keep the API stable over years of evolution.

A useful framing: an API is a contract between teams that don’t talk to each other. The team consuming the API needs to be able to write integration code today that still works in two years. ADACL’s API discipline is what makes that possible — explicit versioning, conservative additions, deprecation only with notice. This lesson is the operational manual for that contract.

API Shape

ADACL exposes two synchronous endpoints and one async stream. Most consumers use a subset.

POST /v1/score

The single-shot scoring endpoint. The consumer sends a feature vector (or a sensor-data payload from which features are computed) and gets back a calibrated score plus explanation metadata.

Request:

{
  "request_id": "uuid-for-trace-correlation",
  "device_id": "device-001",
  "qubit_id": "qubit-7",
  "timestamp": "2026-01-15T10:30:00Z",
  "features": {
    "t2_rolling_mean_60s": 42.3,
    "gate_error_rate": 0.0008,
    "...": "..."
  }
}

Response:

{
  "request_id": "uuid-for-trace-correlation",
  "score": 0.73,
  "model_version": "adacl-2026.01.10",
  "calibration_version": "cal-2026.01.14",
  "top_features": [
    {"name": "t2_rolling_skewness", "contribution": 0.31},
    {"name": "gate_error_rate", "contribution": 0.18},
    {"name": "readout_contrast", "contribution": 0.11}
  ],
  "policy_recommendation": "alert_low",
  "latency_ms": 47
}

Key contract properties:

• The score is calibrated (Lesson 33) — equal increments correspond to equal physical deviation.
• The model_version and calibration_version are returned in every response so the consumer can pin behaviour or audit historical calls.
• top_features is the explanation payload. The consumer can render it directly or use it for routing.
• policy_recommendation is the policy layer’s read on the score for this deployment’s configuration. Consumers that bring their own policy can ignore it.

GET /v1/health

A lightweight endpoint for health checks and version pinning. Consumers use this to verify the API is reachable and which model/calibration is currently live.

Response:

{
  "status": "healthy",
  "model_version": "adacl-2026.01.10",
  "calibration_version": "cal-2026.01.14",
  "uptime_seconds": 84321,
  "drift_dashboards": {
    "score_distribution_drift": "nominal",
    "feature_distribution_drift": "nominal",
    "calibration_error_drift": "nominal"
  }
}

Consumers that care about model freshness poll this every minute; the drift dashboard summary is a useful pre-flight check before relying on a score.

WS /v1/scores/stream

A WebSocket stream that pushes scores as they’re computed. Used by dashboards and high-throughput consumers that don’t want to poll. Each message has the same shape as a POST /v1/score response.

The stream is per-device subscription:

Subscribe: {"device_id": "device-001", "qubits": ["qubit-1", "qubit-7"]}

The server pushes a score message for the selected qubits every time a new score is computed.

SLA Contract

The API ships with an explicit SLA:

• Latency p50: 50ms. The single-shot scoring endpoint should return within 50ms for the median call.
• Latency p99: 250ms. The 99th-percentile call should return within 250ms.
• Availability: 99.9 % over a 30-day rolling window. Equivalent to ~45 minutes of downtime per month.
• Throughput: 1000 scores/sec sustained on a single inference node; 10k/sec horizontally scaled.

These numbers are documented in the API reference and enforced by alerts on the API’s own monitoring dashboard. If the SLA is breached, the consumer can rely on the platform’s incident response; the API team owns the SLA, not the consumer.

Versioning Discipline

The v1 in the URL path is real, not decoration. ADACL’s API versioning rules:

Conservative additions only

Within a major version, the API only changes in backward-compatible ways:

• Adding new fields to responses (consumers ignore unknown fields).
• Adding new optional request fields (server uses defaults if absent).
• Adding new endpoints.
• Loosening validation rules (the server accepts a wider range of inputs).

The following are NOT allowed within v1:

• Removing or renaming response fields.
• Changing the type or semantics of an existing field.
• Adding new required request fields.
• Tightening validation rules.

Anything that breaks an existing consumer requires a major version bump (v2) with a parallel deployment.

Deprecation with notice

When a v2 ships, v1 is supported for at least 12 months in parallel. Deprecation notices appear in v1 responses (X-Deprecation-Notice header) so consumer code can detect the impending sunset. The actual removal of v1 happens only after operational metrics confirm no consumers are still using it.

Model version visibility

The model version is exposed in every response but the model itself can change within a major API version without breaking the contract. A consumer that pins to a specific model version takes responsibility for tracking when that version is deprecated; the API contract doesn’t guarantee specific models forever, only specific schema.

Integration Patterns

Three common consumption patterns:

Pattern 1: Dashboard pull

The dashboard polls /v1/score (or subscribes to /v1/scores/stream) and renders the score. Simple, suitable for low-throughput visualisations.

Pattern 2: Policy-driven mitigation

A separate mitigation service subscribes to the stream, applies its own policy layer to the scores, and triggers automated responses (recalibration, workload pausing, page escalation). The mitigation service is the consumer’s policy layer; ADACL’s policy_recommendation is treated as advisory.

Pattern 3: Observability pipeline ingest

Scores are written into the consumer’s existing observability stack (Prometheus, Datadog, etc.) as labelled metrics. The score lives next to the system’s other monitoring data. Useful for cross-correlation analysis (“the score for qubit 7 was 0.8 right around when the workload latency spiked”).

Pattern 4: Audit-replay

Historical scores are pulled via a separate /v1/scores/replay?from=...&to=... endpoint for retrospective audit. Used by compliance teams and post-incident reviews. The endpoint is rate-limited and authenticated.

What the API Hides

A deliberately-hidden detail: consumers do NOT see ADACL’s internal feature pipeline. The consumer sends a payload (sensor data or pre-computed features); ADACL handles feature engineering internally. The reason: feature engineering is one of the framework’s evolving components, and exposing it to consumers would couple consumer code to internal feature versions. By keeping the feature pipeline behind the API, ADACL can evolve features without coordinating across consumers.

Similar hidden details:

• The CNN architecture is hidden (consumers see the score, not the network).
• The augmentation strategy is hidden (consumers see calibrated scores, not training internals).
• The calibration transformation is hidden (returns transformed scores, not raw model logits).

These hides aren’t arbitrary; each is something that can change between releases without breaking consumer code. Stable API contracts make stable abstraction boundaries.

Authentication and Authorisation

For production deployments the API requires authentication. Typical configurations:

• Service-to-service: mTLS with rotated certificates, scoped to the deployment.
• Internal dashboards: SSO via OIDC, with read-only scope.
• Audit clients: scoped API tokens with rate limits and per-call logging.

Authorisation scopes available in the default deployment:

• scores:read — call /v1/score and stream.
• scores:replay — call /v1/scores/replay.
• health:read — call /v1/health.
• admin:configure — modify policy thresholds. Restricted to ops team.

The API does NOT support models:write or any model-mutation endpoint. Models are deployed via the release pipeline (Lesson 40), not via the API.

Common Integration Mistakes

Three patterns that cause real production incidents:

• Caching the score for too long. ADACL scores are point-in-time; caching beyond 60 seconds defeats the framework’s whole point. Set the cache TTL conservatively or skip caching.
• Ignoring model_version in audit-replay. Replaying historical scores with the current model produces different values than were originally seen. Always pin the model version when replaying.
• Treating policy_recommendation as a guarantee. It’s an advisory output. Consumers that bring their own policy layer should consume the score, not the recommendation; the recommendation can change between releases (within the SLA) while the score’s calibration is the load-bearing contract.

These are the three calls that get made to the API team most often. Documenting them in the integration guide is high-leverage operational hygiene.

Key Takeaways

• Understanding the fundamental concepts: The ADACL API exposes a single-shot scoring endpoint, a health endpoint, and a streaming endpoint. The contract is calibrated score + explanation metadata + model/calibration versions in every response. Versioning is conservative within a major version; v1 → v2 transitions require parallel deployment.
• Practical applications in quantum computing: The API is the integration point for everything that’s not the operator dashboard — policy-driven mitigation services, observability pipelines, audit-replay tools. The feature pipeline, CNN architecture, and calibration internals are hidden behind the API; this is intentional and load-bearing.
• Connection to the broader SNAP ADS framework: Module 9 is about deployment surfaces. Lesson 46 covered the system topology; Lesson 47 covered the quantum-hardware integration; this lesson covers the programmatic interface. Lessons 49 and 50 extend the deployment story to other application domains and future directions.

What’s Next?

Lesson 49 looks beyond quantum hardware: ADACL deployed in medical diagnosis, financial fraud detection, and industrial IoT. The framework’s core design (small-label, physics-constrained, drift-prone) applies anywhere those properties hold; we will see what changes and what stays the same across those domains.

---

Ready to continue? Use the navigation buttons below to move to the next lesson or return to the module overview.