PhantomGuard™ API Docs

Base URL: https://phantomguard.pages.dev

Android app communicates with this API. Dashboard consumes same API. → Open Dashboard

Device Registration & Heartbeat

POST/api/device/register
Register a new device. Returns device_id and api_key to use in all subsequent requests.
// Request body
{
  "name": "My Galaxy S24 Ultra",
  "model": "Samsung Galaxy S24 Ultra",
  "owner_email": "you@example.com",
  "alert_emails": ["you@example.com", "backup@example.com"],
  "fcm_token": "firebase_cloud_messaging_token"
}

// Response
{
  "success": true,
  "device_id": "device_abc123",
  "api_key": "pg_live_xyz...",
  "plan": "pro",
  "trial_ends_at": null
}
POST/api/device/heartbeat Requires Auth Headers
Called every 30s by Android app. Returns pending commands to execute. Also updates device status.
// Headers: X-API-Key: pg_live_xxx, X-Device-ID: device_abc123
// Request body
{
  "battery_level": 87,
  "battery_charging": false,
  "network_type": "LTE",
  "bluetooth_enabled": false,
  "location_enabled": true,
  "screen_on": false,
  "is_locked": false,
  "fcm_token": "updated_fcm_token"
}

// Response — contains pending commands to execute immediately!
{
  "success": true,
  "commands": [
    { "id": 5, "command": "SIREN", "params": "{"duration":30}" },
    { "id": 6, "command": "SNAP_PHOTO", "params": "{"camera":"front"}" }
  ]
}

Location Tracking

POST/api/location Requires Auth Headers
Android app posts GPS location. Automatic reverse geocoding via OpenStreetMap Nominatim.
// Headers: X-API-Key, X-Device-ID
{
  "latitude": 41.8827,
  "longitude": -87.6233,
  "accuracy": 5.0,
  "altitude": 180.0,
  "speed": 0.0,
  "bearing": 45.0,
  "battery_level": 87,
  "provider": "gps"
}
GET/api/location/latest?device_id=xxx Requires Auth Headers
Get the latest GPS location for the authenticated device. Used by the dashboard map.
GET/api/location/history?device_id=xxx&hours=24 Requires Auth Headers
Get GPS location history for the authenticated device for the requested time window.

Security Events & Owner-Approved Media

POST/api/events Requires Auth Headers
Report a security event. Supports multipart/form-data for photo upload. Triggers email alert automatically.
// For events with photo: multipart/form-data
// Fields: event_type, description, latitude, longitude, battery_level, photo (file)
// Event types include: failed_pin | sim_removed | owner_approved_photo | unknown
// Camera/photo events are uploaded only after the protected device approves the request.

// JSON-only events: Content-Type: application/json
{
  "event_type": "failed_pin",
  "description": "Wrong PIN entered 3 times",
  "latitude": 41.8827,
  "longitude": -87.6233,
  "battery_level": 87,
  "network_type": "LTE",
  "attempt_count": 3
}

Remote Commands

POST/api/commands Requires Auth Headers
Authenticated owner queues a command. FCM can push immediately when configured; heartbeat polling is the fallback. Camera and microphone commands require on-device approval.
// Valid commands:
// SIREN, SIREN_STOP, LOCK, SNAP_PHOTO, RECORD_AUDIO,
// STREAM_LOCATION, STROBE_START, STROBE_STOP, BLUETOOTH_ON,
// BLUETOOTH_OFF, VOLUME_MAX, DISPLAY_MESSAGE, FLASHLIGHT_ON,
// FLASHLIGHT_OFF, VIBRATE, PING, WIPE_DATA
// WIPE_DATA also requires params: {"confirm":"CONFIRM"}.

{ "device_id": "device_abc123", "command": "SIREN", "params": {"duration": 30, "volume": 100} }
{ "device_id": "device_abc123", "command": "SNAP_PHOTO", "params": {"camera": "front"} }
{ "device_id": "device_abc123", "command": "LOCK", "params": {"message": "Stolen phone!"} }
{ "device_id": "device_abc123", "command": "DISPLAY_MESSAGE", "params": {"text": "Please return this phone."} }
GET/api/commands/pending Requires Auth Headers
Android app polls this endpoint to get commands to execute. Marks them as delivered.
POST/api/commands/:id/ack Requires Auth Headers
Android app acknowledges a command as executed, failed, or approval_required.

Owner-Approved Audio

POST/api/audio Requires Auth Headers
Upload a recorded audio file (multipart/form-data). Stored in R2 and listed in dashboard.
// multipart/form-data
// Fields: audio (file, .m4a/.mp3), duration (int, seconds)
🔑 Authentication
All device-to-server requests must include:
X-API-Key: pg_live_your_key_here
X-Device-ID: device_your_id_here

These are returned when you register a device. Store them securely in Android SharedPreferences (encrypted).
Open Live Dashboard