InstaAlert Engine™

1. Platform Overview

InstaAlert Engine is a unified safety infrastructure platform that provides location-aware alert routing, evacuation map delivery, and compliance content management through a single API layer.

What InstaAlert Engine Does

Your systems (fire panels, PA, access control, IoT devices) send alerts to InstaAlert Engine. We handle:

Location routing — Alerts reach the correct building, floor, or zone
Visual display — Connected screens show alerts + evacuation maps
Content delivery — The right map, procedures, and instructions for each location
Audit logging — Complete compliance trail for every alert

Dogfooding Architecture

Everything you see in our Campus Ready application uses these exact APIs. When you integrate, you're using the same proven code paths we use internally.

2. Architecture

InstaAlert Engine is built as a platform-first, multi-tenant system with a unified routing engine.

Your Systems (Vendors)

Fire Panels

PA Systems

Access Control

IoT Sensors

Digital Signage

↓ REST API ↓

InstaAlert Engine Platform

/api/v1/alerts

/api/v1/maps

/api/v1/graph

/api/v1/procedures

↓ WebSocket ↓

Campus Displays

Terminal A Gate 15

Concourse B Lobby

Baggage Claim

Admin Building

Multi-Tenant Isolation

Each campus (airport, school, hospital) is a separate tenant. Data isolation is enforced at the database level — Airport A cannot see Airport B's buildings, alerts, or maps, even though they share the same platform.

Location Hierarchy

The Campus Graph Engine models your physical space:

Tenant → Campus → Building → Floor → Room → Zone → Device

Alerts can target any level. A fire in "Terminal B, Floor 2" only displays on screens assigned to that location.

3. Authentication

InstaAlert Engine supports two authentication methods for different use cases:

API Key Authentication (Vendor Path)

For external systems integrating with the platform.

Header Format

Authorization: Bearer sk_live_YOUR_API_KEY

Your API key determines which APIs you can access (based on subscription) and tracks usage for billing.

PIN Authentication (Admin Path)

For campus administrators using the web interface.

Request Body

{ "authPin": "1234", "schoolCode": "AIRPORT-LAX" }

PIN auth bypasses subscription checks — it's for trusted campus admins, not metered vendor usage.

Authentication Comparison

Aspect	API Key (Vendors)	PIN (Admins)
Use Case	External system integration	Campus admin web interface
Usage Tracking	Yes (metered, billed)	No
Subscription Required	Yes (alerts, maps, etc.)	No
Rate Limiting	Per subscription tier	Standard limits

Hybrid Authentication

The /api/v1/alerts endpoint accepts both methods. This enables dogfooding — our admin UI calls the same API you will, just with PIN instead of API key.

4. Example: Fire Panel Integration

This end-to-end scenario shows how a fire panel alarm triggers visual alerts and evacuation maps on the correct displays.

Scenario: Terminal B Fire Alarm

A fire alarm activates in Terminal B, Gate 15 at LAX Airport. The fire panel needs to trigger visual alerts on all Terminal B screens, showing the fire alert message plus the floor-specific evacuation map.

1

Fire Panel Detects Alarm

Your fire panel controller detects the alarm and identifies the zone (Terminal B, Floor 1, Zone 15).

2

Fire Panel Calls Alerts API

The panel's integration module sends a POST request to InstaAlert Engine.

3

InstaAlert Engine Routes Alert

The routing engine identifies all screens assigned to Terminal B and broadcasts the alert via WebSocket.

4

Screens Display Alert + Evac Map

Each screen in Terminal B shows the fire alert and fetches its floor-specific evacuation map from the Maps API.

5

Fire Panel Clears Alert

When the alarm is cleared, the panel calls the clear endpoint and screens return to standby.

Step 2: Send the Alert

curl -X POST https://instaalert.app/api/v1/alerts \
  -H "Authorization: Bearer sk_live_FIRE_PANEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schoolCode": "AIRPORT-LAX",
    "alertType": "fire",
    "message": "Fire alarm activated - Terminal B Gate 15. Evacuate immediately.",
    "buildingCode": "TERMINAL-B"
  }'

Response

{
  "success": true,
  "alert": {
    "alertId": "alert-1701234567890",
    "schoolCode": "AIRPORT-LAX",
    "alertType": "fire",
    "message": "Fire alarm activated - Terminal B Gate 15. Evacuate immediately.",
    "targeting": {
      "type": "building",
      "buildingCodes": ["TERMINAL-B"],
      "floor": null
    },
    "timestamp": "2024-11-29T10:15:30.000Z",
    "recipientCount": 24
  }
}

Step 4: Screens Fetch Evacuation Map

Each display screen automatically calls the Maps API to get its location-specific evacuation map:

GET /api/v1/maps/screen/AIRPORT-LAX/screen-terminal-b-gate-15

Response

{
  "plan": {
    "id": 42,
    "fileUrl": "/uploads/evacuation/terminal-b-floor-1.png",
    "title": "Terminal B Level 1 Evacuation",
    "floor": 1,
    "buildingCode": "TERMINAL-B"
  },
  "source": "api/v1/maps/screen"
}

Step 5: Clear the Alert

curl -X POST https://instaalert.app/api/v1/alerts/clear \
  -H "Authorization: Bearer sk_live_FIRE_PANEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schoolCode": "AIRPORT-LAX"
  }'

5. Alerts API Reference

POST /api/v1/alerts

Send an alert to campus displays. Supports campus-wide, building-specific, or floor-specific targeting.

Authentication

Authorization: Bearer sk_live_YOUR_API_KEY

Request Body

Field	Type	Description
`schoolCode` required	string	Campus identifier (e.g., "AIRPORT-LAX")
`alertType` required	string	"fire", "lockdown", "shelter", "evacuation", "medical", "allclear", "custom"
`message` optional	string	Custom message to display on screens
`buildingCode` optional	string \| array	Target specific building(s). Omit for campus-wide.
`floor` optional	integer	Target specific floor within building
`imageUrl` optional	string	Custom image URL to display

POST /api/v1/alerts/clear

Clear all active alerts and return screens to standby mode.

Request Body

Field	Type	Description
`schoolCode` required	string	Campus identifier

GET /api/v1/alerts/history/{schoolCode}

Retrieve alert history for compliance reporting.

Query Parameters

Field	Type	Description
`limit` optional	integer	Max records to return (default: 50)

6. Maps API Reference

GET /api/v1/maps/screen/{schoolCode}/{screenId}

Retrieve the evacuation map for a specific display screen. This is a public endpoint — no authentication required.

Public Endpoint

Display screens call this without an API key. The screen is identified by its screen ID, which is paired to a building/floor during setup.

Path Parameters

Field	Type	Description
`schoolCode`	string	Campus identifier
`screenId`	string	Unique screen identifier (paired during setup)

Response

{
  "plan": {
    "id": 42,
    "fileUrl": "/uploads/evacuation/terminal-b-floor-1.png",
    "title": "Terminal B Level 1 Evacuation",
    "floor": 1,
    "buildingCode": "TERMINAL-B"
  },
  "source": "api/v1/maps/screen"
}

GET /api/v1/maps?locationId={uuid}

List all maps/attachments for a location. Requires API key authentication.

Query Parameters

Field	Type	Description
`locationId` required	uuid	Campus Graph location UUID
`attachmentType` optional	string	"evacuation_map", "floor_plan", "supporting_doc"
`alertTypes` optional	string	Comma-separated: "fire,evacuation"

7. Campus Graph API

The Campus Graph API provides access to your location hierarchy. Use it to discover buildings, floors, and resolve location identifiers.

GET /api/v1/graph/buildings

List all buildings your API key has access to.

GET /api/v1/graph/buildings/{id}/floors

List floors within a building.

GET /api/v1/graph/locations/resolve?identifier={id}

Resolve a device key, UUID, or slug to its full location path (tenant → campus → building → floor → room).

Tenant Isolation

The Graph API only returns locations within tenants your API key is authorized to access. You cannot query other tenants' data.

8. Quick Start Checklist

Before You Integrate

Obtain your API key from your InstaAlert administrator
Note your schoolCode (campus identifier)
Identify your building codes (e.g., "TERMINAL-A", "MAIN-HALL")
Confirm your subscription includes the alerts API

Test Your Integration

Send a test alert to a single building
Verify screens in that building display the alert
Clear the alert and verify screens return to standby
Check /api/v1/alerts/history/{schoolCode} for the audit log

Go Live

Configure your fire panel / PA / IoT system to call the API
Set up error handling for API failures (retry logic, fallback alerts)
Monitor usage via Super Admin dashboard
Document the integration for your operations team

Need Help?

Contact your InstaAlert administrator for API key provisioning, subscription upgrades, or integration support.

Contents

1. Platform Overview

What InstaAlert Engine Does

2. Architecture

Multi-Tenant Isolation

Location Hierarchy

3. Authentication

API Key Authentication (Vendor Path)

PIN Authentication (Admin Path)

Authentication Comparison

4. Example: Fire Panel Integration

Scenario: Terminal B Fire Alarm

Step 2: Send the Alert

Response

Step 4: Screens Fetch Evacuation Map

Response

Step 5: Clear the Alert

5. Alerts API Reference

Request Body

Request Body

Query Parameters

6. Maps API Reference

Path Parameters

Response

Query Parameters

7. Campus Graph API

8. Quick Start Checklist

Before You Integrate

Test Your Integration

Go Live