---
title: "QNN API"
description: "Quantum Neural Network API — hybrid quantum-classical inference and circuit execution"
canonical: "https://docs.ainative.studio/docs/moonshots/qnn-api"
last-updated: "2026-10-22T17:48:46.689Z"
---

# QNN API

Source: https://docs.ainative.studio/docs/moonshots/qnn-api

> Quantum Neural Network API — hybrid quantum-classical inference and circuit execution

## QNN API — Quantum Neural Network

The QNN (Quantum Neural Network) API lets you train, deploy, and run inference on quantum-enhanced ML models. Use it to predict code quality, optimize energy grids, benchmark quantum vs classical models, and monitor quantum circuit executions.

**Base URL:** `https://qnn.ainative.studio/api/v1`

**Authentication:** All endpoints require an AINative API key.

```http
Authorization: Bearer <your-ainative-api-key>
```

---

## Quick Start

```python
import requests

headers = {"Authorization": "Bearer <your-api-key>"}

## Predict code quality
resp = requests.post(
    "https://qnn.ainative.studio/api/v1/predictions/predict",
    headers=headers,
    json={
        "code": "def add(a, b):\n    return a + b",
        "model_id": "your-model-id",
        "mode": "quantum",
        "optimization_level": 1,
        "domain": "code_quality"
    }
)
print(resp.json())
## { "quality_score": 0.94, "recommendations": [...], "entropy": 0.12 }
```

```typescript
const res = await fetch('https://qnn.ainative.studio/api/v1/predictions/predict', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <your-api-key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: 'def add(a, b):\n    return a + b',
    model_id: 'your-model-id',
    mode: 'quantum',
  }),
});
const { quality_score, recommendations } = await res.json();
```

---

## Health

### `GET /health/simple`
Simple health check — no database dependencies.

**Response**
```json
{ "status": "ok" }
```

### `GET /health/`
Full health check including database and settings.

---

## Models

### `POST /models/`
Create a new quantum model.

**Body**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | ✓ | Model name |
| `description` | string | | Model description |
| `n_qubits` | integer | ✓ | Number of qubits |
| `circuit_depth` | integer | ✓ | Quantum circuit depth |
| `quantum_device` | string | | Target device (e.g. `aws-braket-sv1`) |

**Response** — `ModelResponse`
```json
{
  "id": "mdl_abc123",
  "name": "code-quality-v1",
  "n_qubits": 4,
  "circuit_depth": 12,
  "status": "draft",
  "created_at": "2026-04-25T00:00:00Z"
}
```

### `GET /models/`
List all models with optional filtering and pagination.

**Query params:** `limit`, `offset`, `status`, `quantum_device`

### `GET /models/{model_id}`
Get a specific model by ID.

### `PATCH /models/{model_id}`
Update a model's metadata.

### `DELETE /models/{model_id}`
Delete a model.

### `GET /models/{model_id}/info`
Get detailed metadata — architecture, training history, performance metrics.

---

## Model Versions

### `POST /models/{model_id}/versions`
Create a new version of a model.

### `GET /models/{model_id}/versions`
List all versions for a model.

### `POST /models/{model_id}/versions/{version_id}/training`
Create a training run for a specific model version.

---

## Predictions

### `POST /predictions/predict`
Run inference on a trained QNN model.

**Body**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `code` | string | ✓ | Code to analyze |
| `model_id` | string | ✓ | Model ID to use for prediction |
| `mode` | `basic` \| `llm` \| `quantum` | | Prediction mode (default: `basic`) |
| `optimization_level` | 0–3 | | Circuit optimization level |
| `domain` | string | | Problem domain: `code_quality`, `energy_grid` |

**Response**
```json
{
  "model_id": "mdl_abc123",
  "quality_score": 0.94,
  "recommendations": ["Add type hints", "Reduce cyclomatic complexity"],
  "entropy": 0.12,
  "execution_time": 0.043,
  "domain": "code_quality",
  "interpretation": "High quality — production ready"
}
```

---

## Training

### `POST /training/train`
Train a new QNN model on code examples.

**Body**
| Field | Type | Description |
|-------|------|-------------|
| `examples` | array | Code snippets with quality labels |
| `model_config` | object | Qubit count, circuit depth, device |
| `epochs` | integer | Training epochs |

**Response** — returns `model_id` and initial metrics.

---

## Feature Extraction

### `POST /features/extract-from-code`
Extract code quality features directly from a code string.

**Body**
| Field | Type | Description |
|-------|------|-------------|
| `code` | string | Source code |
| `language` | string | Override language detection |

### `GET /features/extract`
Extract features from a specific file path.

### `POST /features/extract/batch`
Extract features from multiple files in one call.

---

## Quantum Signing

Cryptographically sign and verify QNN models with quantum signatures.

### `POST /signing/sign`
Sign a model — produces a quantum signature bound to the model weights.

**Body:** `{ "model_id": "mdl_abc123" }`

### `POST /signing/verify`
Verify a model's quantum signature hasn't been tampered with.

### `POST /signing/apply`
Apply an existing signature to a model.

---

## Repositories

### `GET /repositories/`
List popular GitHub repositories for analysis.

**Query params**
| Param | Default | Description |
|-------|---------|-------------|
| `min_stars` | 100 | Minimum GitHub stars |
| `limit` | 50 | Results per page (max 100) |
| `language` | | Filter by language |
| `sort_by` | `stars` | `stars`, `updated`, `relevance` |

### `GET /repositories/search` / `POST /repositories/search`
Search repositories by quality criteria or query string.

### `POST /repositories/clone`
Clone a GitHub repository for analysis.

### `POST /repositories/analyze`
Start an async analysis job on a cloned repository.

**Response:** `{ "analysis_id": "..." }`

### `GET /repositories/analyze/{analysis_id}`
Poll the status of a repository analysis job.

---

## Monitoring

### `GET /monitoring/models/{model_id}/logs`
Get training logs for a specific model.

### `GET /monitoring/models/{model_id}/training-summary`
Get aggregated training metrics summary.

### Quantum Metrics

| Endpoint | Description |
|----------|-------------|
| `GET /monitoring/quantum/metrics` | Summary metrics for all quantum executions |
| `GET /monitoring/quantum/executions` | Recent executions (limit 1–100) |
| `GET /monitoring/quantum/devices` | Available quantum devices with usage stats |

### Anomaly Detection

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/monitoring/anomalies/` | List training anomalies (filter by severity, status) |
| GET | `/monitoring/anomalies/{id}` | Get anomaly details |
| POST | `/monitoring/anomalies/{id}/resolve` | Mark anomaly resolved |
| GET | `/monitoring/anomalies/thresholds` | Get detection thresholds |
| POST | `/monitoring/anomalies/thresholds` | Update thresholds |

**Anomaly severities:** `low`, `medium`, `high`

---

## Alerts

### `GET /alerts/`
Get alerts with optional filtering.

**Query params:** `alert_type`, `severity`, `status`

**Alert types:** `stalled_training`, `accuracy_drop`, `abnormal_execution_time`

**Severities:** `info`, `warning`, `error`, `critical`

**Statuses:** `new`, `acknowledged`, `resolved`, `ignored`

### `GET /alerts/{alert_id}` · `PATCH /alerts/{alert_id}`
Get or update a specific alert.

### `GET /alerts/model/{model_id}`
Get all alerts for a model.

---

## Circuit Profiler

Profile quantum circuits across devices before committing to paid runs.

### `POST /circuit-profiler/analyze/`
Profile a quantum circuit on a specific device.

**Body**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `device` | string | ✓ | Target quantum device |
| `n_qubits` | integer (1–100) | ✓ | Number of qubits |
| `circuit_depth` | integer (1–1000) | ✓ | Circuit depth |
| `shots` | integer | | Measurement shots (default: 1000) |
| `circuit_type` | string | | `qnn` (default), etc. |
| `optimization_level` | 0–3 | | Default: 1 |

**Response — `CircuitProfileResults`**
```json
{
  "device": "aws-braket-sv1",
  "n_qubits": 4,
  "circuit_depth": 12,
  "execution_time_ms": 42.3,
  "success_rate": 0.98,
  "cost_usd": 0.0035,
  "gate_counts": { "cnot": 8, "h": 4, "rx": 12 }
}
```

### `POST /circuit-profiler/compare/`
Compare circuit performance across multiple devices simultaneously.

### `GET /circuit-profiler/optimize/`
Get optimization suggestions to reduce gate count or execution time.

### `GET /circuit-profiler/devices/`
List all available quantum devices for profiling.

---

## Cost Estimation

Estimate and compare costs before running on real quantum hardware.

### `GET /cost-estimation/devices`
List available quantum devices with pricing information.

### `GET /cost-estimation/estimate`
Estimate cost for a circuit run.

**Query params**
| Param | Required | Description |
|-------|----------|-------------|
| `device` | ✓ | AWS Braket device |
| `shots` | ✓ | Number of measurement shots |
| `n_qubits` | ✓ | Number of qubits |
| `n_layers` | | Number of circuit layers |

### `POST /cost-estimation/compare`
Compare costs across multiple AWS Braket devices for the same circuit.

---

## Cost Tracking & Budgets

### `GET /cost-tracking/budget-limits`
Get current budget limits.

### `POST /cost-tracking/budget-limits`
Set a budget limit for quantum spending.

**Body**
| Field | Type | Description |
|-------|------|-------------|
| `amount` | number | Budget limit in USD |
| `timeframe` | string | `daily`, `weekly`, `monthly`, `quarterly`, `yearly` |
| `user_id` | string | Scope to a specific user |
| `model_id` | string | Scope to a specific model |

### `POST /cost-tracking/track`
Track cost of a completed quantum execution.

### `GET /cost-tracking/current-costs`
Get current costs for all configured timeframes.

### `GET /cost-tracking/alerts` · `POST /cost-tracking/resolve-alert/{alert_id}`
List and resolve cost budget alerts.

### `POST /cost-tracking/reports`
Generate a detailed cost report for a time range.

---

## Benchmarking

Compare QNN models against classical ML baselines.

### `POST /benchmarking/models/compare`
Run a comparison between a QNN model and classical models.

**Body**
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `model_id` | string | ✓ | QNN model ID |
| `dataset_id` | string | ✓ | Dataset to benchmark on |
| `include_scaling_analysis` | boolean | `true` | Include scaling metrics |
| `classical_models` | array | `[RandomForest, SVM, GradientBoosting]` | Models to compare against |

**Response — `BenchmarkReport`**
```json
{
  "report_id": "rpt_xyz",
  "qnn_model_id": "mdl_abc123",
  "timestamp": "2026-04-25T00:00:00Z",
  "model_comparison": { "qnn": 0.94, "RandomForest": 0.87, "SVM": 0.82 },
  "scaling_analysis": { ... },
  "recommendations": ["QNN shows 8% improvement on sparse feature sets"]
}
```

### `GET /benchmarking/reports`
List all benchmark reports.

### `GET /benchmarking/reports/{report_id}`
Get a full benchmark report with visualizations.

### `POST /benchmarking/scaling-analysis`
Run a dedicated scaling analysis for QNN vs classical.

---

## EnergyGrid Demo

Real-world quantum optimization for energy systems.

### `GET /energygrid/status`
Check EnergyGrid integration status.

### `POST /energygrid/optimize/forecast`
Predict energy demand using a QNN forecasting model.

### `POST /energygrid/optimize/storage`
Optimize battery storage scheduling with quantum optimization.

### `POST /energygrid/optimize/grid-switch`
Configure grid node switching with QNN optimization.

---

## Data Pipelines & Datasets

### `POST /data/pipeline/run`
Run the complete data collection pipeline.

### `GET /data/pipeline/{pipeline_id}`
Get pipeline status.

### `GET /data/datasets`
List available datasets.

**Query params:** `limit` (max 100), `offset`, `format` (`csv`, `json`, `parquet`)

### `GET /data/datasets/{dataset_id}`
Get dataset details.

### `GET /data/datasets/{dataset_id}/download`
Download a dataset in the requested format.

---

## Model Lifecycle

```
draft → training → trained → validating → validated → signed → deployed
```

Use the `/models/{id}` PATCH endpoint to transition states, and `/signing/sign` to produce a cryptographic quantum signature before deployment.