NADIR v1 API

Drift scoring, evidence, and fleet health over REST.

Ingest multi-modal telemetry, score cross-modal residuals, retrieve signed evidence bundles, and publish scenario feeds for simulation teams. All protected routes use Bearer API keys; health and OpenAPI docs stay public for local development.

OpenAPI 3.1 Python SDK TypeScript SDK Idempotency-Key

Authentication

Send Authorization: Bearer <api_key> on every /v1/* request. Local default key with make dev-api: nadir_dev_local_key.

curl — fleet health
curl -s http://127.0.0.1:8000/v1/fleet/health-summary \
  -H "Authorization: Bearer nadir_dev_local_key" | jq .total_vehicles

Core endpoints

Base URL: https://api.nadir.ai/v1 (pilot) or http://127.0.0.1:8000/v1 (local).

POST /telemetry/ingest Normalize sensor frames into fleet state
POST /score/residual CUSUM + Mahalanobis tier classification
GET /evidence/{event_id}/bundle Signed evidence chain for claims
GET /fleet/health-summary Fleet tier counts and analytics
POST /risk/scenario-feed Visualizer-ready simulation parameters
GET /health Public liveness (no API key)
Request — POST /v1/telemetry/ingest
{
  "vehicle_id": "FLEET-204",
  "timestamp": "2026-06-03T16:42:00Z",
  "sensors": {
    "camera_rotation_matrix": [0.99, 0.05, 0.0, -0.05, 0.99, 0.0, 0.0, 0.0, 1.0],
    "radar_range_bias_m": 0.0042,
    "lidar_confidence": 0.91
  },
  "metadata": { "fleet_id": "amazon-detroit-01", "region": "midwest" }
}
Response — POST /v1/score/residual
{
  "vehicle_id": "FLEET-204",
  "tier": "CRITICAL",
  "residual_score": 9.84,
  "confidence": 0.88,
  "evidence_id": "EVB-20260603-B7F2",
  "recommended_action": "calibration_required",
  "cusum_triggered": true
}

Python quickstart

Install from the monorepo and run against a local API.

pip + client
pip install -e "NADIR_SDK/python"
export NADIR_API_KEY=nadir_dev_local_key

from nadir_sdk import NadirClient
client = NadirClient(base_url="http://127.0.0.1:8000")
print(client.fleet_health_summary()["critical_count"])
bundle = client.evidence_bundle("EVB-20260603-B7F2")
client.close()

TypeScript quickstart

Same v1 contract with typed errors and retries.

npm + client
cd NADIR_SDK/typescript && npm install && npm run build

import { NadirClient } from "@nadir/sdk";
const client = new NadirClient({
  baseUrl: "http://127.0.0.1:8000",
  apiKey: process.env.NADIR_API_KEY,
});
const summary = await client.fleetHealthSummary();
await client.close();

Local toolchain

Generate telemetry, replay into the API, export evidence for demos.

  • make dev-api — hot-reload API
  • make gen-telemetry — synthetic JSONL
  • make replay-telemetry — ingest replay
  • make export-evidence — demo artifacts

OpenAPI and schemas

Machine-readable contracts ship in the repo for CI validation and client generation.

ArtifactPath
OpenAPI v1NADIR_SDK/openapi/nadir.v1.yaml
JSON SchemaNADIR_SDK/schemas/v1/
Swagger UI (local)http://127.0.0.1:8000/docs