API Coverage Documentation¶

How this document is produced (2026-09-22 rewrite). The endpoint inventory below was built mechanically from docs/openapi.json (paths × methods), and every Consumer(s) cell is the output of a per-path grep over real frontend source (frontend/src, excluding generated types, mocks, and *.test.* files). There is no committed script that regenerates this document — see Generation & Validation for the exact pipeline.

Overview¶

This document maps backend API endpoints to their frontend consumers and lists the endpoints that intentionally (or not yet) have none.

Surface: 386 paths / 468 operations in docs/openapi.json. Consumed: 385 operations have at least one verified frontend source consumer; 83 do not and are listed in Backend-only endpoints.

Generation & Validation¶

Two automations back this document; neither rewrites it:

1. Spec generation — uv run python scripts/generate-openapi.py writes docs/openapi.json from backend.main:app (add --check to verify the committed spec is current; --force to rewrite it). The generate-openapi pre-commit hook runs the same generator, so the committed spec cannot silently drift.
2. Coverage gate — ./scripts/check-api-coverage.sh (CI job api-coverage) enumerates route decorators under backend/api/routes/ and greps frontend/src per path. It is a read-only pass/fail gate over decorator paths; it writes nothing and does not read docs/openapi.json.

The tables here were rebuilt on 2026-09-22 by a one-off pass: for each docs/openapi.json path, a template-literal-aware regex ({param} → ${…}-or-segment) matched against every non-test, non-mock, non-generated file under frontend/src, including helper-base joins (e.g. fetchGpuConfigApi('/gpu-config') under a /api/system base) and wrapper-function attribution (an exported fetch wrapper in services/ attributes its file, and components importing it count as consumers).

Note: some internal/admin endpoints are intentionally frontend-free; new intentionally-unused endpoints go in the allowlist in scripts/check-api-coverage.sh with a justification comment.

OpenAPI Specification¶

The complete specification is committed at docs/openapi.json and regenerated with:

uv run python scripts/generate-openapi.py            # rewrite docs/openapi.json
uv run python scripts/generate-openapi.py --check    # CI mode: fail if stale

(./scripts/generate-types.sh generates frontend/src/types/generated/api.ts from the app — it writes a throwaway spec under /tmp, not docs/openapi.json.)

Interactive documentation at runtime:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

API Endpoints by Domain¶

One row per method. — means no consumer was found under frontend/src (those rows are collected with reasons in Backend-only endpoints rather than left dangling). The gateway surface POST /api/system/models/{model_name}/load|unload|reload answers 501 by design (Triton runs --model-control-mode=none).

Root, Health & Readiness¶

System¶

Detector Registry¶

Action Events¶

Admin¶

AI Audit¶

Alert Service¶

Alerts¶

Analytics¶

Analytics Zones¶

Audit¶

Auth¶

Auto-Enrollment¶

Backup¶

Calibration¶

Cameras¶

Debug¶

Detections¶

DLQ (Dead Letter Queue)¶

Enrollment Queue¶

Entities¶

Events¶

Exports¶

Face Events¶

Feedback¶

Health¶

Heatmaps¶

Household¶

Household Matcher¶

Jobs¶

Known Persons¶

LLM Reasoning¶

Logs¶

Media¶

Metrics¶

MQTT Config¶

Notification¶

Notification Preferences¶

Outbound Webhooks¶

Plate Reads¶

Prompts¶

Queues¶

Re-ID Search¶

RUM (Real User Monitoring)¶

Scheduled Reports¶

Summaries¶

Tracks¶

V1 Hierarchy (Households, Properties, Areas)¶

Webhooks¶

Zones¶

(WebSocket routes are defined in backend/api/routes/websocket.py and are not listed in the OpenAPI spec.)

WebSocket Message Contracts¶

See WebSocket Contracts for message format specifications.

Backend-only endpoints¶

83 operations have no consumer under frontend/src. The CI coverage gate is green because it keys on decorator paths and string fragments, not on these full path/method rows — treat this as the real backend-only surface:

Queue Names (DLQ)¶

• dlq:detection_queue - Failed detection processing jobs
• dlq:analysis_queue - Failed analysis processing jobs

(Names per backend/core/constants.py — DLQ_PREFIX = "dlq:" + queue.)

Authentication: Destructive operations (requeue, clear) require API key via X-API-Key header or api_key query parameter when api_key_enabled is true.

Frontend-Backend Type Synchronization¶

All TypeScript types are auto-generated from the OpenAPI specification:

# Generate types from the backend OpenAPI schema
./scripts/generate-types.sh

# Check if types are current (CI mode)
./scripts/generate-types.sh --check

Generated types location: frontend/src/types/generated/api.ts

Contract Testing¶

API contract tests ensure responses conform to their documented schemas:

• Backend: backend/tests/contracts/test_api_contracts.py
• Frontend: frontend/tests/contract/ (E2E contract validation)

These validate response structure against the OpenAPI schema, required-field presence, data types, and pagination contracts.

CI/CD Integration¶

Adding New Endpoints¶

1. Define it in the backend with proper OpenAPI documentation.
2. Regenerate: ./scripts/generate-types.sh and uv run python scripts/generate-openapi.py (both are pre-commit hooks).
3. Implement a frontend consumer in the same PR, or add the path to the allowlist in scripts/check-api-coverage.sh with a justification comment.
4. Verify: ./scripts/check-api-coverage.sh.
5. Update this document (or note in the PR that its row is pending — regeneration is the 2026-09-22 one-off pass described above).

Guidelines¶

• New endpoints should have at least one frontend consumer, or an allowlisted justification.
• This document is a snapshot: regenerate the tables (one-off pass described in Generation & Validation) when a domain's surface changes materially, not per PR.
• Contract tests should validate critical response structures.
• WebSocket message formats must match websocket-contracts.md.

Maintained by: Deployment Engineering Team Last Updated: 2026-09-22 (full regeneration from docs/openapi.json; see Generation & Validation)