API DOCUMENTATION

Integrate AeroScope flight tracking data into your applications with our REST API, WebSocket streaming, and zero-trust capability token system. Over 60 endpoints spanning threat projection, sensor fusion, mesh networking, and cross-domain intelligence.

AUTHENTICATION

All API requests require authentication via a bearer token. Obtain your token by authenticating through the login endpoint:

POST /api/auth/login
Content-Type: application/json

{ "password": "your_access_token" }

Response:
{ "token": "eyJhbGci...", "expires_in": "24h" }

Include the token in subsequent requests using the Authorization header:

Authorization: Bearer eyJhbGci...

Tokens expire after 24 hours. Refresh by re-authenticating through the login endpoint.

AIRCRAFT DATA ENDPOINTS

GET /api/aircraft
Returns all currently tracked aircraft with full telemetry: position, altitude, speed, heading, callsign, ICAO hex, aircraft type, and enrichment data.
GET /api/aircraft/:icao
Returns detailed data for a specific aircraft identified by its ICAO 24-bit hex address, including historical positions and analysis results.
GET /api/aircraft/stats
Returns aggregate statistics: total aircraft count, type breakdown, altitude distribution, speed histogram, and coverage metrics.

ANALYSIS ENDPOINTS

GET /api/threats
Returns threat assessments for all tracked aircraft, including threat score (0-100), contributing factors, and classification level.
GET /api/patterns
Returns detected flight patterns: orbits, racetracks, loiter patterns, grid searches, and formation flights with classification confidence.
GET /api/drones
Returns drone detection results with confidence scores, classification rationale, and flight characteristics that triggered detection.
GET /api/airspace/complexity
Returns real-time airspace complexity score with contributing factors and ATC-style recommendations.
GET /api/alerts
Returns active alerts including geofence violations, threat score changes, pattern detections, and anomaly detections.

GEOFENCE ENDPOINTS

GET /api/geofence
Returns all configured geofences with their center coordinates, radius, altitude filters, and current violation status.
POST /api/geofence
Create a new geofence. Required body: { lat, lon, radius_nm, name }. Optional: min_altitude, max_altitude, alert_on_entry, alert_on_exit.

INTELLIGENCE ENDPOINTS

GET /api/threat-projection/:icao
Returns threat cone projection for a specific aircraft: forward-looking reachable airspace volume based on heading, speed, climb rate, and performance envelope. Includes convergence alerts with geofences and other aircraft paths.
GET /api/sensor-fusion
Returns fused sensor data combining ADS-B, acoustic classification, and mesh network observations. Includes per-aircraft confidence scores and source agreement metrics.
GET /api/mesh/status
Returns mesh network status: connected peers, data exchange rates, coverage overlap, and differential privacy parameters. Requires mesh capability token.
GET /api/satellite/status
Returns satellite data source status including Aireon coverage availability, last update timestamps, and aircraft counts from space-based ADS-B feeds.
GET /api/cross-domain
Returns cross-domain fusion results combining RF (ADS-B), acoustic, and mesh observations into unified track records with weighted confidence from each domain.
GET /api/briefing
Returns a natural language situational briefing summarizing current airspace status, active threats, notable aircraft, and recent events. Configurable detail level via ?detail=summary|full.
GET /api/baselines/:icao
Returns the pattern-of-life summary for an aircraft we've seen before: historical typical altitudes, ground speeds, time-of-day distribution, and the current deviation from that envelope.
GET /api/adversarial/metrics
Returns aggregate spoof-detection metrics: per-check trigger rates, integrity-field mismatch counts, and recent flagged aircraft. Useful for monitoring base-rate noise on your particular receivers.

AUTHENTICATION AND CAPABILITY TOKENS

In addition to bearer token authentication, AeroScope implements a zero-trust capability token system for sensitive endpoints. Capability tokens are scoped to specific resources and operations:

POST /api/auth/capability
Request a scoped capability token. Body: { "scope": "mesh|adversarial|briefing|sensor-fusion", "ttl": 3600 }. Returns a short-lived token granting access only to the specified resource scope.

Capability tokens are required for mesh network endpoints, adversarial metrics, and cross-domain fusion. Standard bearer tokens continue to work for aircraft data, analysis, geofence, and export endpoints.

DATA EXPORT ENDPOINTS

GET /api/export/csv
Export current aircraft data as CSV. Optional query parameters: fields (comma-separated field list), filter (aircraft type or threat level).
GET /api/export/json
Export current aircraft data as JSON. Supports the same filtering parameters as CSV export.
GET /api/export/geojson
Export aircraft positions as GeoJSON FeatureCollection for use in GIS tools and mapping applications.

WEBSOCKET STREAMING

Connect to the WebSocket endpoint for real-time data streaming:

ws://aeroscope.live/ws?token=eyJhbGci...

The WebSocket delivers the following message types:

WS aircraft_update
Full aircraft state update broadcast every 12 seconds, containing all tracked aircraft with current positions and analysis results.
WS alert
Real-time alert notifications for geofence violations, high threat scores, pattern detections, and anomaly events.
WS stats
Periodic system statistics including aircraft count, data source status, pipeline performance metrics, and uptime.

RATE LIMITS

API requests are rate-limited to ensure fair access for all users:

Rate limit headers are included in API responses: X-RateLimit-Remaining and X-RateLimit-Reset.

USE CASES