boc/vims-backend/docs/API_PRODUCT_INFO.md

# VIMS & Reality Alerts™ — API Product Information

## Base URL
```
https://api.landvex.com/v1
```

## Authentication
All endpoints require Bearer token authentication:
```
Authorization: Bearer <your_api_key>
```

---

## VIMS Endpoints

### Health Check
```http
GET /health
```

**Response:**
```json
{
  "status": "ok",
  "service": "vims",
  "version": "1.0.0",
  "timestamp": "2026-07-08T19:45:16.656Z"
}
```

### Create Object Type
```http
POST /api/v1/object-types
```

**Request:**
```json
{
  "name": "ATM",
  "slug": "atm",
  "description": "Automated Teller Machine",
  "category": "banking",
  "expectedComponents": [
    {"type": "card_reader"},
    {"type": "pin_pad"},
    {"type": "display"}
  ],
  "riskRules": {
    "skimmer": "red",
    "camera_overlay": "orange"
  }
}
```

### Create Monitored Object
```http
POST /api/v1/objects
```

**Request:**
```json
{
  "objectTypeId": "uuid",
  "name": "ATM-001 Main Street",
  "location": {
    "latitude": 59.3293,
    "longitude": 18.0686,
    "address": "Main Street 1, Stockholm"
  }
}
```

### Submit Observation
```http
POST /api/v1/observations
```

**Request:**
```json
{
  "objectId": "uuid",
  "imageUrl": "https://storage.landvex.com/observations/atm-001-20260708.jpg",
  "metadata": {
    "cameraAngle": "front",
    "lighting": "daylight"
  }
}
```

### Get Detections
```http
GET /api/v1/detections?observationId=uuid
```

**Response:**
```json
{
  "detections": [
    {
      "id": "uuid",
      "objects": [
        {
          "type": "card_reader",
          "confidence": 0.95,
          "bbox": [100, 200, 300, 400]
        }
      ],
      "anomalies": [
        {
          "type": "skimmer_detected",
          "confidence": 0.87,
          "severity": "red"
        }
      ],
      "riskLevel": "red",
      "confidence": 0.87
    }
  ]
}
```

### Get Alerts
```http
GET /api/v1/alerts?status=open&severity=red
```

---

## Reality Alerts™ Endpoints

### Product Info
```http
GET /api/v1/reality-alerts/product/info
```

**Response:**
```json
{
  "success": true,
  "product": {
    "name": "Reality Alerts™",
    "tagline": "Transform verified real-world observations into actionable intelligence",
    "description": "Reality Alerts™ enables anyone to instantly capture and submit verified observations of real-world problems.",
    "positioning": {
      "parent": "QUIXZOOM",
      "role": "Real-time observation engine"
    }
  }
}
```

### Submit Observation
```http
POST /api/v1/reality-alerts
```

**Request:**
```json
{
  "images": [
    "https://storage.quixzoom.com/observations/photo1.jpg"
  ],
  "location": {
    "latitude": 59.3293,
    "longitude": 18.0686
  },
  "description": "Large pothole on Main Street",
  "category": "road_damage"
}
```

**Response:**
```json
{
  "success": true,
  "observationId": "RA-A1B2C3D4",
  "state": "verified",
  "severity": "medium",
  "category": "infrastructure_damage",
  "riskScore": 65,
  "routing": {
    "primary": "municipality",
    "secondary": ["property_owner"],
    "emergency": false
  },
  "reward": {
    "amount": 2.50,
    "currency": "USD"
  }
}
```

### List Alerts
```http
GET /api/v1/reality-alerts?status=open&severity=medium
```

### Get Alert Details
```http
GET /api/v1/reality-alerts/RA-A1B2C3D4
```

### Resolve Alert
```http
POST /api/v1/reality-alerts/RA-A1B2C3D4/resolve
```

**Request:**
```json
{
  "resolution": "fixed",
  "notes": "Pothole filled by road crew",
  "verifiedBy": "uuid"
}
```

### Statistics
```http
GET /api/v1/reality-alerts/stats/overview
```

**Response:**
```json
{
  "success": true,
  "statistics": {
    "totalSubmitted": 1250,
    "totalVerified": 987,
    "totalRejected": 263,
    "verificationRate": 0.79,
    "totalPaidOut": 2847.50
  }
}
```

---

## Error Responses

### 400 Bad Request
```json
{
  "error": "VALIDATION_ERROR",
  "message": "Images and location are required",
  "details": {
    "field": "images",
    "issue": "required"
  }
}
```

### 401 Unauthorized
```json
{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

### 404 Not Found
```json
{
  "error": "NOT_FOUND",
  "message": "Alert not found"
}
```

### 500 Internal Server Error
```json
{
  "error": "INTERNAL_ERROR",
  "message": "An unexpected error occurred"
}
```

---

## Rate Limits

| Endpoint | Limit |
|----------|-------|
| Health | 100/minute |
| Observations | 10/minute |
| Alerts | 50/minute |
| Statistics | 10/minute |

---

## Webhooks

Configure webhooks to receive real-time notifications:

```http
POST /api/v1/webhooks
```

**Request:**
```json
{
  "url": "https://your-domain.com/webhooks/landvex",
  "events": ["alert.created", "alert.resolved"],
  "secret": "your_webhook_secret"
}
```

### Webhook Payload
```json
{
  "event": "alert.created",
  "timestamp": "2026-07-08T19:45:16.656Z",
  "data": {
    "alertId": "RA-A1B2C3D4",
    "severity": "medium",
    "location": {
      "latitude": 59.3293,
      "longitude": 18.0686
    }
  }
}
```