API Reference¶

The Home Security Intelligence system exposes a comprehensive REST API for managing cameras, events, detections, AI pipeline operations, and system configuration.

Base URL¶

http://localhost:8000

For production deployments, replace localhost:8000 with your server address.

Interactive Documentation¶

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI Spec: GET /openapi.json

Authentication¶

The API supports optional API key authentication. When enabled (API_KEY_ENABLED=true), provide the API key via:

HTTP Header (preferred):

X-API-Key: your-api-key

Query Parameter (fallback):

?api_key=your-api-key

Protected endpoints requiring authentication:

• PATCH /api/system/config - Update configuration
• POST /api/system/cleanup - Trigger data cleanup
• POST /api/dlq/requeue/{queue_name} - Requeue DLQ jobs
• DELETE /api/dlq/{queue_name} - Clear DLQ

Content Types¶

Requests: Content-Type: application/json

Responses: Content-Type: application/json

Exceptions:

• Media endpoints return image/* or video/*
• CSV export returns text/csv
• Prometheus metrics returns text/plain

Pagination¶

The API supports two pagination methods:

Cursor-Based Pagination (Recommended)¶

Example:

# First request
GET /api/events?limit=50

# Subsequent requests
GET /api/events?limit=50&cursor=eyJpZCI6IDEyM30=

Response:

{
  "events": [...],
  "count": 150,
  "limit": 50,
  "next_cursor": "eyJpZCI6IDEyM30=",
  "has_more": true
}

Offset-Based Pagination (Deprecated)¶

Using offset triggers a deprecation warning in responses.

Error Handling¶

All errors follow a consistent JSON format:

{
  "detail": "Error message describing what went wrong"
}

Validation Errors (422):

{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

HTTP Status Codes¶

Date/Time Format¶

All timestamps use ISO 8601 format with UTC timezone:

2025-12-23T12:00:00Z

Date filter parameters accept ISO 8601 format:

?start_date=2025-12-23T00:00:00Z&end_date=2025-12-24T00:00:00Z

Rate Limiting¶

Rate limiting uses Redis-based sliding window counters:

Configure via RATE_LIMIT_* environment variables.

API Domain Guides¶

The API is organized into domain-specific guides:

Quick Reference¶

Cameras¶

Events¶

Detections¶

System¶

Real-time¶

Calibration¶

Webhooks¶