# Reality Alert™ API Documentation

## Overview

Reality Alert™ is part of the Landvex Reality Intelligence Platform. It handles spontaneous observations from Zoomers, AI-verifies them, and routes them to the correct recipients.

## Architecture

```
Zoomer Observation
    │
    ▼
AI Analysis (Object Detection + Change Detection)
    │
    ├── Normal → Rejected
    │
    ├── Unclear → Request More Info
    │
    └── Anomaly Detected
            │
            ▼
    Severity Classification
            │
            ▼
    Category Identification
            │
            ▼
    Routing Intelligence
            │
            ▼
    Alert Creation & Notification
            │
            ▼
    Zoomer Reward Calculation
```

## API Endpoints

### Submit Observation

```http
POST /api/v1/reality-alerts
Authorization: Bearer <token>
Content-Type: application/json

{
  "imageUrl": "https://example.com/photo.jpg",
  "gpsLocation": {
    "lat": 59.3293,
    "lng": 18.0686,
    "address": "Stureplan, Stockholm"
  },
  "description": "Dark liquid leaking from pump station",
  "objectType": "pump_station"
}
```

**Response (Verified):**
```json
{
  "status": "verified",
  "alertId": "RA-312C45EE",
  "severity": "high",
  "category": "leak",
  "riskScore": 75,
  "routing": {
    "primary": "water_utility",
    "secondary": ["property_owner", "emergency_services"],
    "emergency": false
  },
  "reward": {
    "amount": 7.5,
    "currency": "USD"
  }
}
```

**Response (Rejected):**
```json
{
  "status": "rejected",
  "reason": "normal_state",
  "message": "Observation appears to be normal condition",
  "reward": {
    "amount": 0.1,
    "currency": "USD",
    "reason": "participation"
  }
}
```

### List Alerts

```http
GET /api/v1/reality-alerts?severity=high&category=leak&limit=50
Authorization: Bearer <token>
```

### Get Alert Details

```http
GET /api/v1/reality-alerts/RA-312C45EE
Authorization: Bearer <token>
```

### Resolve Alert

```http
POST /api/v1/reality-alerts/RA-312C45EE/resolve
Authorization: Bearer <token>
Content-Type: application/json

{
  "resolution": "fixed",
  "notes": "Leak repaired by maintenance team"
}
```

### Get Statistics

```http
GET /api/v1/reality-alerts/stats/overview
Authorization: Bearer <token>
```

## Alert Categories & Routing

| Category | Primary Recipient | Secondary | Emergency |
|----------|------------------|-----------|-----------|
| leak | water_utility | property_owner, emergency_services | No |
| missing | municipality | property_owner, police | No |
| safety_hazard | emergency_services | municipality, property_owner | Yes |
| environmental | environmental_authority | municipality, property_owner | Yes |
| infrastructure_damage | municipality | property_owner, contractor | No |
| malfunction | operator | maintenance, property_owner | No |
| blockage | municipality | water_utility, property_owner | No |
| vandalism | police | property_owner, insurance | No |
| weather_related | municipality | property_owner, emergency_services | No |

## Reward Structure

| Severity | Multiplier | Example Reward |
|----------|-----------|----------------|
| low | 1x | $0.50 |
| medium | 2x | $1.00 |
| high | 5x | $2.50 |
| critical | 10x | $5.00 |

Category bonuses apply on top of severity multiplier.

## Severity Levels

- **LOW**: Minor issue, routine maintenance
- **MEDIUM**: Noticeable problem, needs attention
- **HIGH**: Serious issue, urgent response needed
- **CRITICAL**: Emergency, immediate action required

## Integration with Reality Intelligence Platform

```
Reality Intelligence
├── Scheduled Missions      → Planned inspections
├── Reality Alerts™         → Spontaneous observations (this API)
├── Intelligence Signals    → Pattern analysis
└── Predictive Intelligence → Future predictions
```