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

GET /health

Response:

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

Create Object Type

POST /api/v1/object-types

Request:

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

POST /api/v1/objects

Request:

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

Submit Observation

POST /api/v1/observations

Request:

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

Get Detections

GET /api/v1/detections?observationId=uuid

Response:

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

GET /api/v1/alerts?status=open&severity=red

---

Reality Alerts™ Endpoints

Product Info

GET /api/v1/reality-alerts/product/info

Response:

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

POST /api/v1/reality-alerts

Request:

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

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

GET /api/v1/reality-alerts?status=open&severity=medium

Get Alert Details

GET /api/v1/reality-alerts/RA-A1B2C3D4

Resolve Alert

POST /api/v1/reality-alerts/RA-A1B2C3D4/resolve

Request:

{
  "resolution": "fixed",
  "notes": "Pothole filled by road crew",
  "verifiedBy": "uuid"
}

Statistics

GET /api/v1/reality-alerts/stats/overview

Response:

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

---

Error Responses

400 Bad Request

{
  "error": "VALIDATION_ERROR",
  "message": "Images and location are required",
  "details": {
    "field": "images",
    "issue": "required"
  }
}

401 Unauthorized

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

404 Not Found

{
  "error": "NOT_FOUND",
  "message": "Alert not found"
}

500 Internal Server Error

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

POST /api/v1/webhooks

Request:

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

Webhook Payload

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