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.

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

Quick Start

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 }

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

{ "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

{
  "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

{
  "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

{
  "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

{
  "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.

Quick Start
Health
- GET /health/simple
- GET /health/
Models
Model Versions
Predictions
- POST /predictions/predict
Training
- POST /training/train
Feature Extraction
Quantum Signing
Repositories
Monitoring
Alerts
Circuit Profiler
Cost Estimation
Cost Tracking & Budgets
Benchmarking
EnergyGrid Demo
Data Pipelines & Datasets
Model Lifecycle

Quick Start​

Health​

GET /health/simple​

GET /health/​

Models​

POST /models/​

GET /models/​

GET /models/{model_id}​

PATCH /models/{model_id}​

DELETE /models/{model_id}​

GET /models/{model_id}/info​

Model Versions​

POST /models/{model_id}/versions​

GET /models/{model_id}/versions​

POST /models/{model_id}/versions/{version_id}/training​

Predictions​

POST /predictions/predict​

Training​

POST /training/train​

Feature Extraction​

POST /features/extract-from-code​

GET /features/extract​

POST /features/extract/batch​

Quantum Signing​

POST /signing/sign​

POST /signing/verify​

POST /signing/apply​

Repositories​

GET /repositories/​

GET /repositories/search / POST /repositories/search​

POST /repositories/clone​

POST /repositories/analyze​

GET /repositories/analyze/{analysis_id}​

Monitoring​

GET /monitoring/models/{model_id}/logs​

GET /monitoring/models/{model_id}/training-summary​

Quantum Metrics​

Anomaly Detection​

Alerts​

GET /alerts/​

GET /alerts/{alert_id} · PATCH /alerts/{alert_id}​

GET /alerts/model/{model_id}​

Circuit Profiler​

POST /circuit-profiler/analyze/​

POST /circuit-profiler/compare/​

GET /circuit-profiler/optimize/​

GET /circuit-profiler/devices/​

Cost Estimation​

GET /cost-estimation/devices​

GET /cost-estimation/estimate​

POST /cost-estimation/compare​

Cost Tracking & Budgets​

GET /cost-tracking/budget-limits​

POST /cost-tracking/budget-limits​

POST /cost-tracking/track​

GET /cost-tracking/current-costs​

GET /cost-tracking/alerts · POST /cost-tracking/resolve-alert/{alert_id}​

POST /cost-tracking/reports​

Benchmarking​

POST /benchmarking/models/compare​

GET /benchmarking/reports​

GET /benchmarking/reports/{report_id}​

POST /benchmarking/scaling-analysis​

EnergyGrid Demo​

GET /energygrid/status​

POST /energygrid/optimize/forecast​

POST /energygrid/optimize/storage​

POST /energygrid/optimize/grid-switch​

Data Pipelines & Datasets​

POST /data/pipeline/run​

GET /data/pipeline/{pipeline_id}​

GET /data/datasets​

GET /data/datasets/{dataset_id}​

GET /data/datasets/{dataset_id}/download​

Model Lifecycle​

Quick Start

Health

`GET /health/simple`

`GET /health/`

Models

`POST /models/`

`GET /models/`

`GET /models/{model_id}`

`PATCH /models/{model_id}`

`DELETE /models/{model_id}`

`GET /models/{model_id}/info`

Model Versions

`POST /models/{model_id}/versions`

`GET /models/{model_id}/versions`

`POST /models/{model_id}/versions/{version_id}/training`

Predictions

`POST /predictions/predict`

Training

`POST /training/train`

Feature Extraction

`POST /features/extract-from-code`

`GET /features/extract`

`POST /features/extract/batch`

Quantum Signing

`POST /signing/sign`

`POST /signing/verify`

`POST /signing/apply`

Repositories

`GET /repositories/`

`GET /repositories/search` / `POST /repositories/search`

`POST /repositories/clone`

`POST /repositories/analyze`

`GET /repositories/analyze/{analysis_id}`

Monitoring

`GET /monitoring/models/{model_id}/logs`

`GET /monitoring/models/{model_id}/training-summary`

Quantum Metrics

Anomaly Detection

Alerts

`GET /alerts/`

`GET /alerts/{alert_id}` · `PATCH /alerts/{alert_id}`

`GET /alerts/model/{model_id}`

Circuit Profiler

`POST /circuit-profiler/analyze/`

`POST /circuit-profiler/compare/`

`GET /circuit-profiler/optimize/`

`GET /circuit-profiler/devices/`

Cost Estimation

`GET /cost-estimation/devices`

`GET /cost-estimation/estimate`

`POST /cost-estimation/compare`

Cost Tracking & Budgets

`GET /cost-tracking/budget-limits`

`POST /cost-tracking/budget-limits`

`POST /cost-tracking/track`

`GET /cost-tracking/current-costs`

`GET /cost-tracking/alerts` · `POST /cost-tracking/resolve-alert/{alert_id}`

`POST /cost-tracking/reports`

Benchmarking

`POST /benchmarking/models/compare`

`GET /benchmarking/reports`

`GET /benchmarking/reports/{report_id}`

`POST /benchmarking/scaling-analysis`

EnergyGrid Demo

`GET /energygrid/status`

`POST /energygrid/optimize/forecast`

`POST /energygrid/optimize/storage`

`POST /energygrid/optimize/grid-switch`

Data Pipelines & Datasets

`POST /data/pipeline/run`

`GET /data/pipeline/{pipeline_id}`

`GET /data/datasets`

`GET /data/datasets/{dataset_id}`

`GET /data/datasets/{dataset_id}/download`

Model Lifecycle