API DOCS
Docs / Reality Alerts API

Reality Alerts API Reference

Subscribe to real-world event streams and receive webhook notifications when conditions match your geographic and severity criteria.

📍
Base path: https://api.aamos.ai/v1/reality-alerts/
🌍
Webhook delivery: Your webhook_url must be publicly accessible and respond with HTTP 200 within 5 seconds. Failed deliveries are retried up to 3 times with exponential backoff.

POST /v1/reality-alerts/subscriptions

POST /v1/reality-alerts/subscriptions

Create a new alert subscription. You will receive webhook notifications when real-world events matching your criteria are detected within the specified bounding box.

Request — application/json

FieldTypeRequiredDescription
webhook_urlstringRequiredHTTPS URL to receive POST notifications when alerts trigger.
categoriesstring[]RequiredEvent categories to subscribe to. See category list below.
bboxfloat[4]RequiredGeographic bounding box: [west, south, east, north] in WGS84 decimal degrees.
min_severityintegerOptionalMinimum severity level (1–5). Default: 1 (all severities).

Alert Categories

CategoryDescription
fireFire and wildfire events
floodFlooding and water events
infrastructureInfrastructure failures (power, roads, utilities)
securitySecurity incidents and public safety events
weatherSevere weather conditions
environmentalEnvironmental events and hazards

Example Request

bash 
curl -X POST https://api.aamos.ai/v1/reality-alerts/subscriptions \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-app.example.com/hooks/alerts",
    "categories": ["fire", "flood", "infrastructure"],
    "bbox": [17.8, 59.2, 18.2, 59.4],
    "min_severity": 3
  }'

Response — 201 Created

json 
{
  "subscription_id": "sub_8c2f1a3e5b",
  "status": "active",
  "webhook_url": "https://your-app.example.com/hooks/alerts",
  "categories": ["fire", "flood", "infrastructure"],
  "bbox": [17.8, 59.2, 18.2, 59.4],
  "min_severity": 3,
  "created_at": "2025-01-15T09:00:00Z"
}

Webhook Payload Example

When an alert triggers, your webhook receives a POST with this body:

json 
{
  "event": "alert.triggered",
  "subscription_id": "sub_8c2f1a3e5b",
  "alert": {
    "alert_id": "alt_9d1e7b4f2c",
    "category": "fire",
    "severity": 4,
    "title": "Wildfire reported near monitored area",
    "location": { "lat": 59.31, "lng": 18.05 },
    "detected_at": "2025-01-15T11:00:00Z"
  }
}

GET /v1/reality-alerts/subscriptions

GET /v1/reality-alerts/subscriptions

List all active subscriptions for your API key.

bash 
curl https://api.aamos.ai/v1/reality-alerts/subscriptions \
  -H "Authorization: Bearer ak_live_YOUR_KEY"

Response — 200 OK

json 
{
  "subscriptions": [
    {
      "subscription_id": "sub_8c2f1a3e5b",
      "status": "active",
      "categories": ["fire", "flood"],
      "created_at": "2025-01-15T09:00:00Z"
    }
  ]
}

DELETE /v1/reality-alerts/subscriptions/:id

DELETE /v1/reality-alerts/subscriptions/:id

Cancel and delete a subscription. You will stop receiving webhook notifications immediately.

bash 
curl -X DELETE https://api.aamos.ai/v1/reality-alerts/subscriptions/sub_8c2f1a3e5b \
  -H "Authorization: Bearer ak_live_YOUR_KEY"

Response — 204 No Content

An empty 204 response confirms deletion.

GET /v1/reality-alerts/alerts

GET /v1/reality-alerts/alerts

Query historical alerts matching your filters. Useful for backfill, auditing, or building dashboards.

Query Parameters

ParameterTypeRequiredDescription
fromstringOptionalISO 8601 timestamp. Filter alerts detected after this time.
tostringOptionalISO 8601 timestamp. Filter alerts detected before this time.
categorystringOptionalFilter by alert category (e.g. fire, flood).
min_severityintegerOptionalMinimum severity level (1–5).
bash 
curl "https://api.aamos.ai/v1/reality-alerts/alerts?from=2025-01-01T00:00:00Z&category=fire&min_severity=3" \
  -H "Authorization: Bearer ak_live_YOUR_KEY"

Response — 200 OK

json 
{
  "alerts": [
    {
      "alert_id": "alt_9d1e7b4f2c",
      "category": "fire",
      "severity": 4,
      "title": "Wildfire reported near monitored area",
      "location": { "lat": 59.31, "lng": 18.05 },
      "detected_at": "2025-01-15T11:00:00Z"
    }
  ],
  "total": 1
}

GET /v1/reality-alerts/alerts/:alert_id

GET /v1/reality-alerts/alerts/:alert_id

Retrieve the full details of a specific alert by ID, including enriched metadata.

bash 
curl https://api.aamos.ai/v1/reality-alerts/alerts/alt_9d1e7b4f2c \
  -H "Authorization: Bearer ak_live_YOUR_KEY"

Response — 200 OK

json 
{
  "alert_id": "alt_9d1e7b4f2c",
  "category": "fire",
  "severity": 4,
  "title": "Wildfire reported near monitored area",
  "description": "Active fire detected within your subscription area. Estimated spread: 2.3 km².",
  "location": {
    "lat": 59.31,
    "lng": 18.05,
    "radius_m": 800
  },
  "sources": ["satellite", "sensor_network"],
  "detected_at": "2025-01-15T11:00:00Z",
  "updated_at": "2025-01-15T11:45:00Z",
  "status": "active"
}