Events API¶

The Events API provides endpoints for managing security events in the NEM home security monitoring system. Events are aggregated collections of detections that represent security-relevant activities.

Source: backend/api/routes/events.py

Overview¶

Events are created when the AI pipeline detects security-relevant activity. Each event:

• Contains one or more detections
• Has an LLM-generated risk score (0-100)
• Includes a summary and reasoning from Nemotron
• Supports soft-delete for recovery

Endpoints¶

List Events¶

GET /api/events

List security events with optional filtering and pagination.

Source: backend/api/routes/events.py:224-468

Query Parameters¶

Response¶

{
  "items": [
    {
      "id": 1,
      "camera_id": "front_door",
      "started_at": "2026-01-23T12:00:00Z",
      "ended_at": "2026-01-23T12:02:30Z",
      "risk_score": 75,
      "risk_level": "medium",
      "summary": "Person detected near front entrance",
      "reasoning": "Person approaching entrance during daytime, no suspicious behavior",
      "llm_prompt": "<|im_start|>system\nYou are a home security risk analyzer...",
      "reviewed": false,
      "notes": null,
      "snooze_until": null,
      "detection_count": 5,
      "detection_ids": [1, 2, 3, 4, 5],
      "thumbnail_url": "/api/detections/1/image",
      "enrichment_status": {
        "status": "full",
        "successful_models": ["violence", "weather", "face", "clothing"],
        "failed_models": [],
        "errors": {},
        "success_rate": 1.0
      },
      "deleted_at": null
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0,
    "next_cursor": "eyJpZCI6IDUwLCAiY3JlYXRlZF9hdCI6ICIyMDI2LTAxLTIzVDEyOjAwOjAwWiJ9", // pragma: allowlist secret
    "has_more": true
  },
  "deprecation_warning": null
}

Source: backend/api/schemas/events.py:147-193

HTTP Status Codes¶

Get Event Statistics¶

GET /api/events/stats

Get aggregated event statistics including risk distribution and per-camera counts.

Source: backend/api/routes/events.py:471-603

Query Parameters¶

Response¶

{
  "total_events": 44,
  "events_by_risk_level": {
    "critical": 2,
    "high": 5,
    "medium": 12,
    "low": 25
  },
  "risk_distribution": [
    { "risk_level": "critical", "count": 2 },
    { "risk_level": "high", "count": 5 },
    { "risk_level": "medium", "count": 12 },
    { "risk_level": "low", "count": 25 }
  ],
  "events_by_camera": [
    {
      "camera_id": "front_door",
      "camera_name": "Front Door",
      "event_count": 30
    },
    {
      "camera_id": "back_door",
      "camera_name": "Back Door",
      "event_count": 14
    }
  ]
}

Source: backend/api/schemas/events.py:243-284

Get Timeline Summary¶

GET /api/events/timeline-summary

Get bucketed event data for timeline visualization. Supports different zoom levels with varying bucket sizes.

Source: backend/api/routes/events.py:621-779

Query Parameters¶

Response¶

{
  "buckets": [
    {
      "timestamp": "2026-01-15T06:00:00Z",
      "event_count": 5,
      "max_risk_score": 45
    },
    {
      "timestamp": "2026-01-15T07:00:00Z",
      "event_count": 12,
      "max_risk_score": 85
    }
  ],
  "total_events": 17,
  "start_date": "2026-01-15T06:00:00Z",
  "end_date": "2026-01-15T08:00:00Z"
}

Source: backend/api/schemas/events.py:287-349

Search Events¶

GET /api/events/search

Full-text search across events using PostgreSQL text search.

Source: backend/api/routes/events.py:782-892

Query Parameters¶

Response¶

Results include a relevance_score field indicating search match quality.

Export Events¶

GET /api/events/export

Export events as CSV or Excel file.

Source: backend/api/routes/events.py:895-999

Query Parameters¶

Response¶

Returns file download with appropriate Content-Type header.

Rate Limiting: Export tier (5 requests/minute)

Get Single Event¶

GET /api/events/{event_id}

Get detailed information about a specific event.

Path Parameters¶

Response¶

Returns full EventResponse object.

HTTP Status Codes¶

Update Event¶

PATCH /api/events/{event_id}

Update event metadata (reviewed status, notes, snooze).

Path Parameters¶

Request Body¶

{
  "reviewed": true,
  "notes": "Verified - delivery person",
  "snooze_until": "2026-01-24T12:00:00Z"
}

Source: backend/api/schemas/events.py:127-144

HTTP Status Codes¶

Delete Event¶

DELETE /api/events/{event_id}

Soft-delete an event. The event can be restored later.

Path Parameters¶

HTTP Status Codes¶

Restore Event¶

POST /api/events/{event_id}/restore

Restore a soft-deleted event.

Path Parameters¶

HTTP Status Codes¶

List Deleted Events¶

GET /api/events/deleted

List soft-deleted events for the "trash" view.

Source: backend/api/schemas/events.py:352-393

Response¶

Returns DeletedEventsListResponse with same structure as list events.

Bulk Operations¶

Bulk Create Events¶

POST /api/events/bulk

Create multiple events in a single request.

Rate Limiting: Bulk tier (10 requests/minute)

Request Body¶

{
  "events": [
    {
      "camera_id": "front_door",
      "started_at": "2026-01-23T12:00:00Z",
      "risk_score": 45
    }
  ]
}

Response¶

Returns HTTP 207 Multi-Status with per-item results.

Bulk Update Events¶

PATCH /api/events/bulk

Update multiple events in a single request.

Rate Limiting: Bulk tier (10 requests/minute)

Bulk Delete Events¶

DELETE /api/events/bulk

Delete multiple events in a single request.

Rate Limiting: Bulk tier (10 requests/minute)

Related Endpoints¶

Get Event Detections¶

GET /api/events/{event_id}/detections

Get all detections associated with an event.

Get Event Enrichments¶

GET /api/events/{event_id}/enrichments

Get enrichment data for all detections in an event.

Generate Event Clip¶

POST /api/events/{event_id}/clip

Generate a video clip for an event.

Data Models¶

EventResponse¶

Source: backend/api/schemas/events.py:61-125

EnrichmentStatusResponse¶

Source: backend/api/schemas/events.py:27-58

Validation Rules¶

Date Range Validation¶

• start_date must be before end_date
• Dates are normalized to end-of-day for date-only inputs
• Maximum date range: 90 days

Sparse Fieldsets¶

Valid fields for the fields parameter:

• id, camera_id, started_at, ended_at
• risk_score, risk_level, summary, reasoning
• reviewed, notes, detection_count, thumbnail_url

Related Documentation¶

• Detections API - Detection data endpoints
• Error Handling - Error response formats
• Request/Response Schemas - Schema details