leocrm/docs/api-documentation.md

# LeoCRM API Documentation

> Auto-generated from FastAPI route enumeration. **295 endpoints** across **30 tag groups**.

## Overview

LeoCRM exposes a RESTful API under `/api/v1/`. All endpoints (except `/api/v1/health` and `/api/v1/auth/login`) require authentication via session cookie.

- **Swagger UI**: `/docs`
- **ReDoc**: `/redoc`
- **OpenAPI JSON**: `/openapi.json`

### Authentication

1. Call `POST /api/v1/auth/login` with `{email, password}` → receives session cookie.
2. Include the session cookie in all subsequent requests.
3. Call `POST /api/v1/auth/logout` to invalidate the session.

### Multi-Tenancy

All data is tenant-scoped. The tenant context is derived from the authenticated session. Users with multiple tenants can switch via `POST /api/v1/auth/switch-tenant`.

### Error Format

```json
{"detail": "Error message", "code": "error_code", "fields": {"field": "error"}}
```

### Pagination

List endpoints use `page` (1-based) and `page_size` (1-100) query parameters. Responses include `total`, `page`, `page_size`, and `items`.

---

## Core Routes

### health (1 endpoint)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/health` | Health check — no auth required. Returns status + DB/Redis/storage/worker checks. **Response model**: `HealthResponse` |

### metrics (1 endpoint)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/metrics` | Prometheus metrics endpoint. |

### auth (7 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/v1/auth/login` | Login with email+password. Sets session cookie. **Request**: `LoginRequest`, **Response**: `AuthResponse` |
| POST | `/api/v1/auth/logout` | Logout — invalidate session, clear cookie. **Response**: `MessageResponse` |
| GET | `/api/v1/auth/me` | Get current user + active tenant. **Response**: `AuthResponse` |
| GET | `/api/v1/auth/me/permissions` | Get resolved permissions for current user. |
| POST | `/api/v1/auth/switch-tenant` | Switch active tenant. **Request**: `SwitchTenantRequest` |
| POST | `/api/v1/auth/password-reset/request` | Request password reset email. **Request**: `PasswordResetRequest` |
| POST | `/api/v1/auth/password-reset/confirm` | Confirm password reset with token. **Request**: `PasswordResetConfirm` |

### users (5 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/users` | List users with pagination. **Response**: `PaginatedUsers` |
| POST | `/api/v1/users` | Create a new user (admin only). **Request**: `UserCreate`, **Response**: `UserResponse` |
| GET | `/api/v1/users/{user_id}` | Get a single user. **Response**: `UserResponse` |
| PATCH | `/api/v1/users/{user_id}` | Update user fields. **Request**: `UserUpdate` |
| DELETE | `/api/v1/users/{user_id}` | Delete/deactivate a user. |

### roles (5 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/roles` | List all roles. |
| POST | `/api/v1/roles` | Create a custom role. |
| GET | `/api/v1/roles/permissions` | Get all available permission definitions. |
| PATCH | `/api/v1/roles/{role_id}` | Update role permissions. |
| DELETE | `/api/v1/roles/{role_id}` | Delete a custom role. |

### groups (9 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/groups` | List all groups. |
| POST | `/api/v1/groups` | Create a new group. |
| GET | `/api/v1/groups/{group_id}` | Get a single group. |
| PATCH | `/api/v1/groups/{group_id}` | Update group. |
| DELETE | `/api/v1/groups/{group_id}` | Delete group. |
| GET | `/api/v1/groups/{group_id}/members` | List group members. |
| POST | `/api/v1/groups/{group_id}/members` | Add member to group. |
| DELETE | `/api/v1/groups/{group_id}/members/{user_id}` | Remove member from group. |
| GET | `/api/v1/groups/user/{user_id}` | Get groups for a user. |

### tenants (4 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/tenants` | List tenants for current user. |
| POST | `/api/v1/tenants` | Create a new tenant. |
| GET | `/api/v1/tenants/{tenant_id}/users` | List users in a tenant. |
| POST | `/api/v1/tenants/{tenant_id}/users` | Add user to tenant. |

### notifications (6 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/notifications` | List notifications with pagination. |
| PATCH | `/api/v1/notifications/{notification_id}/read` | Mark notification as read. |
| GET | `/api/v1/notifications/unread-count` | Get unread count. **Response**: `UnreadCountResponse` |
| GET | `/api/v1/notifications/types` | List notification types. |
| GET | `/api/v1/notifications/preferences` | Get notification preferences. |
| PATCH | `/api/v1/notifications/preferences/{type_key}` | Update notification preference. |

### contacts (10 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/contacts` | List contacts with pagination, FTS search, type/folder filter, sorting. |
| POST | `/api/v1/contacts` | Create a contact (company or person). |
| GET | `/api/v1/contacts/export` | Stream contacts as CSV. |
| GET | `/api/v1/contacts/{contact_id}` | Get a single contact. |
| PUT | `/api/v1/contacts/{contact_id}` | Update contact. |
| DELETE | `/api/v1/contacts/{contact_id}` | Soft-delete contact. |
| GET | `/api/v1/contacts/{contact_id}/persons` | List contact persons. |
| POST | `/api/v1/contacts/{contact_id}/persons` | Add contact person. |
| PUT | `/api/v1/contacts/{contact_id}/persons/{person_id}` | Update contact person. |
| DELETE | `/api/v1/contacts/{contact_id}/persons/{person_id}` | Delete contact person. |

### contact-folders (6 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/contact-folders` | List contact folders. |
| POST | `/api/v1/contact-folders` | Create a folder. |
| PUT | `/api/v1/contact-folders/{folder_id}` | Update folder. |
| DELETE | `/api/v1/contact-folders/{folder_id}` | Delete folder. |
| PUT | `/api/v1/contact-folders/{folder_id}/reorder` | Reorder folder. |
| PUT | `/api/v1/contact-folders/contacts/{contact_id}/move` | Move contact to folder. |

### entity-history (3 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/entity-history/{entity_type}/{entity_id}` | Get change history for an entity. |
| POST | `/api/v1/entity-history/undo/{entity_type}/{entity_id}` | Undo last change. |
| POST | `/api/v1/entity-history/restore` | Restore entity to a specific version. |

### import-export (2 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/v1/import` | Import data from file. |
| POST | `/api/v1/import/preview` | Preview import data. |

### plugins (11 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/plugins` | List all plugins. |
| GET | `/api/v1/plugins/manifest` | Get plugin manifest schema. |
| GET | `/api/v1/plugins/active-manifests` | Get manifests of all active plugins. |
| POST | `/api/v1/plugins/install-url` | Install plugin from URL. |
| POST | `/api/v1/plugins/upload` | Upload and install plugin ZIP. |
| POST | `/api/v1/plugins/{name}/install` | Install a discovered plugin. |
| POST | `/api/v1/plugins/{name}/activate` | Activate a plugin. |
| POST | `/api/v1/plugins/{name}/deactivate` | Deactivate a plugin. |
| GET | `/api/v1/plugins/{name}/config` | Get plugin configuration. |
| PATCH | `/api/v1/plugins/{name}/config` | Update plugin configuration. |
| DELETE | `/api/v1/plugins/{name}` | Uninstall a plugin. |

### ai-copilot (3 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/v1/ai/copilot/query` | Ask the AI copilot a question. |
| POST | `/api/v1/ai/copilot/execute` | Execute an AI copilot action. |
| GET | `/api/v1/ai/copilot/history` | Get copilot conversation history. |

### workflows (10 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/workflows` | List workflow definitions. |
| POST | `/api/v1/workflows` | Create a workflow. |
| GET | `/api/v1/workflows/{workflow_id}` | Get a workflow. |
| PATCH | `/api/v1/workflows/{workflow_id}` | Update a workflow. |
| DELETE | `/api/v1/workflows/{workflow_id}` | Delete a workflow. |
| POST | `/api/v1/workflows/{workflow_id}/instances` | Start a workflow instance. |
| GET | `/api/v1/workflows/instances` | List workflow instances. |
| GET | `/api/v1/workflows/instances/{instance_id}` | Get a workflow instance. |
| POST | `/api/v1/workflows/instances/{instance_id}/advance` | Advance workflow to next step. |
| POST | `/api/v1/workflows/instances/{instance_id}/cancel` | Cancel a workflow instance. |

### user-preferences (4 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/user/preferences` | Get all user preferences. |
| GET | `/api/v1/user/preferences/{key}` | Get a specific preference. |
| PUT | `/api/v1/user/preferences/{key}` | Set a preference. |
| DELETE | `/api/v1/user/preferences/{key}` | Delete a preference. |

### currencies (4 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/currencies` | List currencies. |
| POST | `/api/v1/currencies` | Create a currency. |
| PATCH | `/api/v1/currencies/{currency_id}` | Update a currency. |
| DELETE | `/api/v1/currencies/{currency_id}` | Delete a currency. |

### taxes (4 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/taxes` | List tax rates. |
| POST | `/api/v1/taxes` | Create a tax rate. |
| PATCH | `/api/v1/taxes/{tax_id}` | Update a tax rate. |
| DELETE | `/api/v1/taxes/{tax_id}` | Delete a tax rate. |

### sequences (4 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/sequences` | List number sequences. |
| POST | `/api/v1/sequences` | Create a sequence. |
| PATCH | `/api/v1/sequences/{sequence_id}` | Update a sequence. |
| DELETE | `/api/v1/sequences/{sequence_id}` | Delete a sequence. |

### system-settings (2 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/system-settings` | Get system settings. **Response**: `SystemSettingsResponse` |
| PUT | `/api/v1/system-settings` | Upsert system settings. **Request**: `SystemSettingsUpsert`, **Response**: `SystemSettingsResponse` |

### attachments (4 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/attachments` | List attachments. |
| POST | `/api/v1/attachments` | Upload an attachment. |
| GET | `/api/v1/attachments/{attachment_id}` | Download an attachment. |
| DELETE | `/api/v1/attachments/{attachment_id}` | Delete an attachment. |

### addresses (4 endpoints)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/addresses` | List addresses. |
| POST | `/api/v1/addresses` | Create an address. |
| PATCH | `/api/v1/addresses/{address_id}` | Update an address. |
| DELETE | `/api/v1/addresses/{address_id}` | Delete an address. |

### audit (1 endpoint)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/audit-log` | Query audit log entries. |

---

## Plugin Routes

### automation (Automation & Agents)

Agent Builder, Automation Builder, Cron-Scheduler, Agent Runner.

| Method | Path | Description |
|--------|------|-------------|
| GET/POST | `/api/v1/automation/*` | Automation definitions, triggers, execution logs. |

### agents (AI Agents)

Phase F — Agent system: CRUD, execution, streaming, runs, tools, skills, approvals, monitoring, AI use-case, unified tasks.

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/agents` | List agent definitions. |
| POST | `/api/v1/agents` | Create an agent definition. |
| GET | `/api/v1/agents/{id}` | Get an agent definition. |
| PATCH | `/api/v1/agents/{id}` | Update an agent definition (optimistic lock via `version`). |
| DELETE | `/api/v1/agents/{id}` | Delete an agent definition. |
| POST | `/api/v1/agents/{id}/execute` | Execute an agent (manual trigger). |
| GET | `/api/v1/agents/{id}/stream` | Stream agent run steps (SSE). |
| GET | `/api/v1/agents/{id}/runs` | List runs for an agent. |
| GET | `/api/v1/agents/{id}/runs/{run_id}/steps` | List steps for a run. |
| GET | `/api/v1/agents/tools` | List available agent tools. |
| GET | `/api/v1/agents/monitor/stats` | Agent monitor statistics. |
| GET | `/api/v1/agents/{id}/ai-use-case` | Get AI use-case metadata. |
| PATCH | `/api/v1/agents/{id}/ai-use-case` | Update AI use-case metadata. |

### skills (AI Skills)

Phase F — Skill registry for agent capabilities.

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/skills` | List skills. |
| POST | `/api/v1/skills` | Register a skill. |
| PATCH | `/api/v1/skills/{id}` | Update a skill. |
| DELETE | `/api/v1/skills/{id}` | Delete a skill. |

### approvals (Approval Requests)

Phase F — Human approval workflow for agent actions.

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/approvals` | List approval requests (filters: status, entity_type, entity_id, requested_by). |
| POST | `/api/v1/approvals` | Create an approval request. |
| POST | `/api/v1/approvals/{id}/approve` | Approve a pending request. |
| POST | `/api/v1/approvals/{id}/reject` | Reject a pending request. |

### unified-tasks (Unified Tasks)

Phase F — Polymorphic task assignment, subtasks, and goals.

| Method | Path | Description |
|--------|------|-------------|
| GET/POST | `/api/v1/unified-tasks/*` | Unified task CRUD with polymorphic assignment. |
| GET/POST | `/api/v1/unified-tasks/*/subtasks` | Subtask management. |
| GET/POST | `/api/v1/unified-tasks/*/goals` | Goal management. |

### dms (Document Management System)

19 endpoints for file and folder management.

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/dms/files` | List files. |
| POST | `/api/v1/dms/files/upload` | Upload a file. |
| GET | `/api/v1/dms/files/{file_id}` | Get file metadata. |
| GET | `/api/v1/dms/files/{file_id}/preview` | Preview a file. |
| POST | `/api/v1/dms/files/{file_id}/share` | Share a file. |
| GET/POST | `/api/v1/dms/folders` | Folder CRUD. |
| GET | `/api/v1/dms/search` | Search documents. |
| GET | `/api/v1/dms/shared-with-me` | Files shared with current user. |

### mail (Email Integration)

50 endpoints for IMAP/SMTP email management.

| Method | Path | Description |
|--------|------|-------------|
| GET/POST | `/api/v1/mail/accounts` | Email account management. |
| GET/POST | `/api/v1/mail/folders` | Folder management. |
| GET | `/api/v1/mail/{mail_id}` | Get a specific email. |
| POST | `/api/v1/mail/send` | Send an email. |
| POST | `/api/v1/mail/drafts` | Save draft. |
| GET | `/api/v1/mail/search` | Search emails. |
| GET | `/api/v1/mail/threads` | List email threads. |
| POST | `/api/v1/mail/pgp/keys` | PGP key management. |
| POST | `/api/v1/mail/rules` | Mail filter rules. |
| POST | `/api/v1/mail/vacation` | Vacation responder. |

### calendar (Calendar & Scheduling)

21 endpoints for calendar management.

| Method | Path | Description |
|--------|------|-------------|
| GET/POST | `/api/v1/calendar/entries` | Calendar entry CRUD. |
| GET/POST | `/api/v1/calendars` | Calendar CRUD. |
| GET | `/api/v1/calendar/kanban` | Kanban board view. |
| POST | `/api/v1/calendar/import` | Import ICS. |
| GET | `/api/v1/calendar/{calendar_id}/ics-feed` | ICS feed. |
| POST | `/api/v1/resources` | Resource booking. |

### search (Unified Search)

Hybrid cross-entity search (PostgreSQL FTS + pgvector) with KI query understanding, RRF rank fusion, visibility filtering, and field-level RBAC.

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/search` | Hybrid search via query params (same as POST). |
| POST | `/api/v1/search` | Hybrid search with KI query understanding. |
| GET | `/api/v1/search/suggest` | Autocomplete suggestions (FTS prefix). |
| POST | `/api/v1/search/similar` | Find similar entities across all types by embedding. |
| POST | `/api/v1/search/reindex` | Trigger reindexing of entity types (admin). |
| GET | `/api/v1/search/providers` | List active search providers + capability flags. |
| POST | `/api/v1/search/providers/{entity_type}/toggle` | Toggle a provider on/off (admin). |
| GET | `/api/v1/search/stats` | Search index statistics (indexed/pending per table). |
| GET | `/api/v1/search/facets` | Available facets (entity types, tags, date ranges). |
| POST | `/api/v1/search/rebuild/{entity_type}/{entity_id}` | Rebuild index for a single entity (admin). |
| POST | `/api/v1/search/purge/{entity_type}/{entity_id}` | Purge entity from index (admin, GDPR). |

> **MCP:** Unified search is also exposed as an MCP tool named `search` (category `search`, permission `search:read`) via the MCP server plugin (`app/plugins/builtins/mcp_server/tool_definitions.py`).

#### Search Request (POST `/api/v1/search`)

```json
{
  "query": "Max Mustermann",
  "entity_types": ["contact", "mail"],
  "limit": 20,
  "offset": 0,
  "date_from": "2026-01-01",
  "date_to": "2026-12-31",
  "tags": ["vip", "partner"],
  "sort": "relevance"
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `query` | string | — | Search query (1–500 chars, required). |
| `entity_types` | list[string] | all | Restrict search to these entity types. |
| `limit` | int | 20 | Max results (1–100). |
| `offset` | int | 0 | Pagination offset. |
| `date_from` | string | null | ISO date `YYYY-MM-DD` — filter by `created_at`/`updated_at >= date_from`. |
| `date_to` | string | null | ISO date `YYYY-MM-DD` — filter by `created_at`/`updated_at <= date_to`. |
| `tags` | list[string] | null | Filter results by tags (comma-separated on entities). |
| `sort` | string | `relevance` | Sort order: `relevance`, `date`, `name`. |

#### Search Response

```json
{
  "query": "Max Mustermann",
  "normalized_query": "max mustermann",
  "results": [
    {
      "entity_type": "contact",
      "entity_id": "uuid",
      "title": "Max Mustermann",
      "snippet": "max@example.com",
      "score": 0.95,
      "data": {"type": "person"}
    }
  ],
  "facets": {"types": {"contact": 1}},
  "summary": "1 Ergebnis",
  "suggestions": []
}
```

| Field | Type | Description |
|-------|------|-------------|
| `query` | string | Original query. |
| `normalized_query` | string | KI-normalized query. |
| `results` | list[SearchResult] | Ranked results (entity_type, entity_id, title, snippet, score, data). |
| `facets` | object | KI-generated facet counts. |
| `summary` | string | Human-readable summary. |
| `suggestions` | list[string] | Suggested follow-up filters. |

#### GET `/api/v1/search` Query Params

Same fields as the POST body, passed as query parameters: `q` (required), `entity_types` (comma-separated), `limit`, `offset`, `date_from`, `date_to`, `tags` (comma-separated), `sort`.

#### GET `/api/v1/search/suggest`

Query params: `q` (required, 1–200), `limit` (default 10, 1–50). Returns `{"suggestions": ["..."]}`.

#### POST `/api/v1/search/similar`

Body: `{"entity_type": "contact", "entity_id": "uuid", "limit": 5}`. Returns `{"similar": {"mail": [SearchResult...], ...}}`.

#### POST `/api/v1/search/reindex`

Body: `{"entity_types": ["contact"], "include_chunks": true}`. Returns `{"status": "ok", "entity_types": [...], "include_chunks": true, "job_ids": [...]}`. Requires `search:admin`.

#### GET `/api/v1/search/providers`

Returns a list of providers: `{"entity_type", "plugin_name", "is_active", "supports_fts", "supports_vector", "supports_rag", "supports_graph"}`.

#### GET `/api/v1/search/facets`

Returns `{"entity_types": [...], "tags": [...], "date_ranges": {"contacts": {"min": "...", "max": "..."}, ...}}`.

#### GET `/api/v1/search/stats`

Returns per-table `{"total", "indexed", "pending"}` plus `recent_logs` (last 10 index log entries).

#### POST `/api/v1/search/rebuild/{entity_type}/{entity_id}` / `/purge/{entity_type}/{entity_id}`

Admin-only. Rebuild regenerates the embedding + TSV; purge sets embedding/TSV to NULL (and removes chunks for files). Returns `{"status": "ok"|"failed", "entity_type", "entity_id", "message"}`.

### reports (Report Generator)

8 endpoints for report templates and generation.

| Method | Path | Description |
|--------|------|-------------|
| GET/POST | `/api/v1/reports/templates` | Report template CRUD. |
| POST | `/api/v1/reports/generate` | Generate a report. |
| GET | `/api/v1/reports/{report_id}` | Get report status. |
| GET | `/api/v1/reports/{report_id}/download` | Download generated report. |

### entity-links (Entity Linking)

4 endpoints for connecting entities.

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/contacts/{contact_id}/files` | Get files linked to a contact. |
| POST/DELETE | `/api/v1/dms/files/{file_id}/link` | Link/unlink a file to an entity. |
| GET | `/api/v1/dms/files/{file_id}/links` | Get all links for a file. |

### kommunikation (Unified Messaging)

23 endpoints for conversations and messages.

| Method | Path | Description |
|--------|------|-------------|
| GET/POST | `/api/v1/comm/conversations` | Conversation CRUD. |
| GET/POST | `/api/v1/comm/conversations/{id}/messages` | Message list and send. |
| POST | `/api/v1/comm/conversations/{id}/participants` | Manage participants. |
| POST | `/api/v1/comm/messages/{id}/reactions` | Message reactions. |
| GET | `/api/v1/comm/miniapps` | List mini-apps. |

### ai-proactive (Proactive AI)

8 endpoints for AI insights and suggestions.

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/ai-proactive/suggestions` | Get AI suggestions. |
| GET | `/api/v1/ai-proactive/suggestions/stream` | SSE stream of suggestions. |
| POST | `/api/v1/ai-proactive/suggestions/{id}/act` | Act on a suggestion. |
| POST | `/api/v1/ai-proactive/suggestions/{id}/dismiss` | Dismiss a suggestion. |
| GET/PUT | `/api/v1/ai-proactive/settings` | Proactive AI settings. |

### ai-assistant (AI Assistant)

30 endpoints for AI chat sessions, providers, models, and tools.

| Method | Path | Description |
|--------|------|-------------|
| GET/POST | `/api/v1/ai/sessions` | Chat session CRUD. |
| GET | `/api/v1/ai/sessions/{id}/messages` | List messages in session. |
| POST | `/api/v1/ai/sessions/{id}/stream` | Stream chat completion (SSE). |
| GET/POST | `/api/v1/ai/providers` | AI provider CRUD. |
| GET/POST | `/api/v1/ai/models` | AI model CRUD. |
| GET/POST | `/api/v1/ai/presets` | Preset CRUD. |
| GET | `/api/v1/ai/tools` | List available AI tools. |

### ai-ui-control (AI UI Control)

WebSocket and REST endpoints for AI-driven UI control.

| Method | Path | Description |
|--------|------|-------------|
| WebSocket | `/ws/ai-ui-control` | Real-time UI command stream. |
| POST | `/api/v1/ai-ui-control/command` | Send UI command from AI agent. |

### tags (Tag Management)

8 endpoints for tag CRUD and assignment.

| Method | Path | Description |
|--------|------|-------------|
| GET/POST | `/api/v1/tags` | Tag CRUD. |
| POST/DELETE | `/api/v1/tags/assign` | Assign/remove tag from entity. |
| POST | `/api/v1/tags/bulk-assign` | Bulk assign tags. |
| GET | `/api/v1/tags/{tag_id}/entities` | Get entities with a tag. |

### permissions (Permission Management)

5 endpoints for file-level permissions and share links.

| Method | Path | Description |
|--------|------|-------------|
| GET/POST | `/api/v1/dms/files/{file_id}/permissions` | File permission CRUD. |
| POST | `/api/v1/dms/files/{file_id}/share-link` | Create public share link. |
| DELETE | `/api/v1/dms/share-links/{link_id}` | Revoke share link. |

### public-share (Public Sharing)

2 endpoints — no auth required, token-based access.

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/public/share/{token}` | Access shared resource via token. |
| POST | `/api/public/share/{token}` | Interact with shared resource. |

---

## Schema Examples

### LoginRequest
```json
{"email": "admin@leocrm.local", "password": "secure-password"}
```

### AuthResponse
```json
{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "admin@leocrm.local",
  "name": "Admin User",
  "role": "admin",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440001",
  "tenant_name": "Acme GmbH"
}
```

### UserCreate
```json
{
  "email": "user@leocrm.local",
  "name": "John Doe",
  "password": "secure-password",
  "role": "viewer",
  "is_active": true
}
```

### UserResponse
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@leocrm.local",
  "name": "John Doe",
  "role": "viewer",
  "is_active": true,
  "tenant_id": "550e8400-e29b-41d4-a716-446655440001"
}
```

### HealthResponse
```json
{"status": "healthy", "version": "1.0.0"}
```

### UnreadCountResponse
```json
{"count": 5}
```

---

## KI Integration Notes

### For AI Agents

1. **Health Check**: Run `python scripts/ai_health_check.py --base-url <url> --token <token>` before and after updates.
2. **Deploy**: Use `python scripts/ai_deploy.py --dry-run` to preview, then `python scripts/ai_deploy.py` for real deployment.
3. **OpenAPI**: The full OpenAPI spec is available at `/openapi.json` — use it for dynamic endpoint discovery.
4. **Safe Methods**: GET endpoints are safe to probe. POST/PUT/DELETE require careful payload construction.
5. **Session Auth**: AI agents should call `POST /api/v1/auth/login` first, then use the returned cookie for all subsequent requests.

---

## Phase G — Workflow MVP Endpoints

### Workflow CRUD
| Method | Path | Description | Permission |
|--------|------|-------------|-----------|
| GET | `/api/v1/workflows` | List workflows (paginated) | `workflows:read` |
| POST | `/api/v1/workflows` | Create workflow definition | `workflows:write` |
| GET | `/api/v1/workflows/{id}` | Get workflow by ID | `workflows:read` |
| PATCH | `/api/v1/workflows/{id}` | Update workflow | `workflows:write` |
| DELETE | `/api/v1/workflows/{id}` | Delete workflow | `workflows:write` |

### Workflow Instances
| Method | Path | Description | Permission |
|--------|------|-------------|-----------|
| GET | `/api/v1/workflows/instances` | List instances (paginated) | `workflows:read` |
| POST | `/api/v1/workflows/{id}/instances` | Create instance | `workflows:write` |
| GET | `/api/v1/workflows/instances/{id}` | Get instance by ID | `workflows:read` |
| POST | `/api/v1/workflows/instances/{id}/advance` | Advance to next step | `workflows:write` |
| POST | `/api/v1/workflows/instances/{id}/cancel` | Cancel instance | `workflows:write` |
| POST | `/api/v1/workflows/instances/{id}/resume` | Resume waiting instance (G-RUN) | `workflows:write` |
| GET | `/api/v1/workflows/instances/{id}/history` | Step history / execution log (G-LOG) | `workflows:read` |

### Triggers (G-EVT, G-MAN, G-WEB)
| Method | Path | Description | Permission |
|--------|------|-------------|-----------|
| POST | `/api/v1/workflows/{id}/trigger` | Manual trigger (G-MAN) | `workflows:write` |
| POST | `/api/v1/workflows/webhook/{token}` | Incoming webhook trigger (G-WEB) | Token-based |

### Approval (G-APPROVAL)
| Method | Path | Description | Permission |
|--------|------|-------------|-----------|
| POST | `/api/v1/workflows/instances/{id}/approve` | Approve current step | `workflows:write` |
| POST | `/api/v1/workflows/instances/{id}/reject` | Reject current step | `workflows:write` |

### Templates (G-UI-TEMPL)
| Method | Path | Description | Permission |
|--------|------|-------------|-----------|
| GET | `/api/v1/workflows/templates` | List workflow templates | `workflows:read` |
| POST | `/api/v1/workflows/templates/{id}/instantiate` | Create workflow from template | `workflows:write` |

### Step Types (14 total)
| Type | Description | Config Fields |
|------|-------------|---------------|
| `action` | Execute configured action | `action_type`, `user_id`, `notification_*` |
| `approval` | Pause for human approval | (none) |
| `notification` | Send notification | `user_id`, `title`, `body`, `notification_type` |
| `condition` | Branch on condition | `field`, `operator`, `value`, `on_true_step`, `on_false_step` |
| `wait` | Wait/delay (G-WAIT) | `duration_seconds` or `resume_at` |
| `http` | HTTP request (G-HTTP) | `method`, `url`, `headers`, `body`, `timeout_seconds`, `response_mapping` |
| `mail` | Send email (G-MAIL) | `to`, `subject`, `body`, `account_id` |
| `calendar` | Calendar event (G-CAL) | `action`, `title`, `start`, `end`, `event_id` |
| `dms` | DMS interaction (G-DMS) | `action`, `query`, `file_id` |
| `search` | Unified search (G-SEARCH) | `query`, `entity_type`, `limit` |
| `agent` | Invoke AI agent (G-AGENT) | `agent_id`, `input`, `wait_for_completion` |
| `crm` | CRM action (G-CRM) | `action`, `data`, `entity_id` |
| `event` | Publish event (G-EVT) | `event_name`, `payload` |
| `webhook` | Outgoing webhook (G-WEB) | `url`, `method`, `headers`, `body` |

### Durable WorkflowRun (G-RUN)
- `status`: `pending` → `in_progress` → `waiting` → `in_progress` → `completed` / `failed` / `cancelled`
- `resume_at`: ISO datetime when waiting instance should be resumed
- `resume_reason`: `wait`, `approval`, `retry`, `event`, `webhook`
- `step_state`: JSONB — per-step output stored for data flow between steps (G-CTX)
- `retry_count` / `max_retries`: Retry with exponential backoff (G-RETRY)
- `lock_owner` / `lock_expires_at`: Redis lock for concurrency control
- `idempotency_key`: Deduplication for side-effect steps (G-IDEMP)
- `error_message`: Last error message if failed

### SSRF Protection (G-HTTP)
HTTP and webhook steps block:
- Private/internal IP ranges (10.x, 172.16-31.x, 192.168.x)
- Localhost (127.0.0.1, ::1, localhost)
- Cloud metadata endpoints (metadata.google.internal)
- Non-HTTP/HTTPS schemes (ftp, file, gopher)

### Automated-Decision Guard (G-HUMAN-DEC)
Workflow steps with `ai_use_case_metadata` containing `risk_level >= medium` or `requires_approval: true` or `auto_execute: false` require human approval before execution. High-risk actions (send_email, delete_entity, execute_payment, etc.) require review even at low risk levels.