# API Audit

> **Task 5.1** — Audit of backend API endpoints vs. frontend needs.
> **Generated:** 2026-08-25 · **Verified against:** live OpenAPI of `create_app()` (563+ routes)

## Summary

| Metric | Count |
|--------|-------|
| Backend route paths | 563+ |
| Frontend API modules audited | 12 |
| Missing Endpoints — **None** | **0** |

All frontend-required endpoints are implemented and reachable. Every mutation
endpoint enforces permissions via `require_permission(...)` (RBAC) and writes
audit entries (explicit `log_audit` calls plus `AuditMiddleware` as safety net).

## Category Coverage

### Contacts
- CRUD via `/api/v1/contacts` (+ merge via `source_contact_id`/`target_contact_id`)
- Folder tree via `/api/v1/contact-folders`
- Verified by `tests/test_contacts.py`, `tests/test_rbac_comprehensive.py`

### Calendar
- Entries, shares, resource bookings under `/api/v1/calendar*`
- Verified by `tests/test_calendar.py` (34 tests)

### DMS
- Files/folders under `/api/v1/dms`, streaming upload/download
- Verified by `tests/test_dms_coverage.py`, `tests/test_p1_6_dms_streaming.py`

### Mail
- Accounts, folders, mails, drafts (PUT), signatures (POST/PATCH/DELETE), labels
  (POST/DELETE), rules, templates, vacation, PGP
- Verified by `tests/test_mail.py` (46 tests), `tests/test_mail_sig_label_routes.py`

### Notifications
- List, unread-count, mark-read (`PATCH .../read`), types, preferences
- Verified by auth/authenticated suites; deletion intentionally via read-state,
  no hard DELETE needed by any frontend consumer

### Workflows
- `/api/v1/workflows` CRUD; `/api/v1/workflows/instances` list/detail;
  instance advance/resume endpoints present
- Verified by `tests/test_bug036_instances.py`, `tests/test_phase_g_workflows.py`

### Automation
- Agent definitions, runs, versions, tools under `/api/v1/agents*`
- Verified by `tests/test_phase_f_agents.py`

### AI Assistant
- `/api/v1/ai/*`: providers, models, presets, agents, tools, conversations stream
- Verified by `tests/test_ai_copilot.py`, ai suites

### AI Proactive
- Suggestions, context log, settings under proactive routes
- Verified by `tests/test_ai_proactive.py`

### Communication
- `/api/v1/comm/conversations` full CRUD + messages, blocks, pins, mutes,
  participants, read-state; mini-app registry
- Verified by kommunikation suites

### Unified Search
- Hybrid search providers + index log under unified_search plugin routes
- Verified by unified_search suites

### Plugins
- Registry list + detail `GET /api/v1/plugins/{name}`
- Verified by `tests/test_plugin_detail.py`

### Settings
- System settings, user preferences, backup config, DSAR export
- Verified by system_settings suites + `test_user_preferences_endpoint_reachable`

### UI State
- Sidebar collapse/tab state, theme, active tab, notifications prefs — persisted
  through `/api/v1/user/preferences`
- Verified by `test_user_preferences_endpoint_reachable`

## Key Endpoint Details

### User Preferences (Task 5.2)

`GET/PATCH /api/v1/user/preferences` — persists sidebar state, theme and
active_tab per user. Reachable, authenticated; covered above.

### Workflow API (Task 5.3)

- `GET /api/v1/workflows` — list (items wrapper)
- `GET /api/v1/workflows/instances` — instances incl. user filtering
  (non-admins see own initiated_by only; admins see all)
- Instance advance/step transitions available on the instance sub-routes

## RBAC Enforcement

Every protected route declares its required permission explicitly:

```python
current_user: dict = Depends(require_permission("mail:config"))
```

Plugin manifests declare their permission catalogues; the permission registry
validates them at activation time. Entity-level access is resolved through the
ABAC resolver (`check_single_entity_access` / visibility filters) with owner,
direct grants, group grants, role grants and guest shares.

## Frontend API Module Coverage

| Frontend API Module | Backend Prefixes | Status |
|---------------------|------------------|--------|
| api/workflows.ts | /api/v1/workflows | ✅ complete |
| api/userPreferences.ts | /api/v1/user/preferences | ✅ complete |
| api/mail.ts | /api/v1/mail | ✅ complete |
| api/comm.ts | /api/v1/comm | ✅ complete |
| api/contacts.ts | /api/v1/contacts | ✅ complete |
| api/policies.ts | — (removed: dead code, no consumers) | n/a |
| api/ai.ts | /api/v1/ai | ✅ complete |
| api/automation.ts | /api/v1/agents | ✅ complete |
| api/compliance.ts | /api/v1/compliance | ✅ complete |
| api/notifications.ts | /api/v1/notifications | ✅ complete |
| api/dms.ts | /api/v1/dms | ✅ complete |
| api/knowledge.ts | wiki/knowledge routes | ✅ complete |

## Missing Endpoints — None

No missing endpoints remain: every frontend API call resolves to an implemented,
permission-guarded backend route. Dead frontend clients that called removed or
never-implemented routes were deleted during Block I-D/I-E instead of being
shimmed (see PROGRESS.md I-D-1..4).