API Documentation

Send device heartbeat

Endpoint for defense devices to send heartbeat data including system status and operational metrics. Recommended interval: every 5 minutes while monitoring, every 15 minutes in sleep mode.

{
  "api_key": "550e8400-e29b-41d4-a716-446655440000",
  "local_time": "2024-01-15T10:30:00Z",
  "firmware": "v2.1.0",
  "ai_model_version": "defense-v1.2.3",
  "wifi_signal_strength": -45,
  "local_ip": "192.168.20.17",
  "uptime": 86400.5,
  "status": "monitoring"
}

CORS preflight request

Handles CORS preflight requests for cross-origin access

Submit defense event

Endpoint for defense devices to submit image-recognition detections, spray responses and sleep-mode transitions with pre-uploaded media files using the optimized two-step process

{
  "api_key": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "detection",
  "start_time": "2024-01-15T14:30:15Z",
  "end_time": "2024-01-15T14:30:17Z",
  "confidence": 0.87,
  "target_class": "cat",
  "metadata": {
    "detection_zone": "front_yard"
  }
}

CORS preflight request

Handles CORS preflight requests for cross-origin access

Pair device with a 6-digit code

The user generates a 6-digit code in the web app. The device sends the code here and receives its permanent api_key. Codes expire after 15 minutes and can be used once.

Read desired settings

On boot/reconnect or changed heartbeat version. No additional periodic settings polling. Returns model metadata, last report sequence and an additive class_configuration extension outside the strict Settings v3 object. Email-only changes also increment settings_version.

Submit versioned local changes

Persist base_version, mutation_id, changes and optional class_configuration before sending. Replay the identical mutation after uncertain delivery. Action/email changes are atomic. With class_configuration, changes may be empty for an email-only save. HTTP 409 returns the current snapshot; class edits including email are one conflict group.

Report effective settings

A successful PUT is not an apply acknowledgment. Persist monotonic report_sequence and exact body before sending; report actual effective settings and, when supported, class_configuration. Applied reports must match the referenced revision; extended reports also match current version and email preferences.

Register an event idempotently

Persist client_event_id and replay the identical body. Do not also send to legacy defense-events.

Reserve a private media upload

Raw PUT to upload_url with Content-Type and Content-Length, without device key. Valid for 2 hours. The role identifies an ordered capture. Reusing client_media_id links one immutable file (for example a shared clip) without uploading it again. Images <=10 MiB, MP4 <=50 MiB.

Confirm a stored media file

Verifies existence, size and MIME before exposing to the owner. Repeat safely after timeouts.

Permanently delete an event from the device

Use only for an explicit user deletion on the device. Automatic local retention must not call this endpoint. Replays of an already deleted event succeed idempotently.

List pending cloud-initiated event deletions

Acknowledge locally applied event deletions

Fetch the active annotation target catalog

Returns the global, versioned classes that a reviewer can assign to existing device-side Bounding Boxes. The device fetches this endpoint when annotation_catalog_version in a heartbeat response advances.