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

{"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)

Method	Path	Description
GET/POST/PUT/DELETE	/api/v1/agents/*	AI agent CRUD and runner endpoints.

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)

7 endpoints for cross-entity search.

Method	Path	Description
POST	/api/v1/search	Unified search across all entities.
GET	/api/v1/search/providers	List search providers.
POST	/api/v1/search/reindex	Rebuild search index.
POST	/api/v1/search/similar	Find similar entities.
GET	/api/v1/search/suggest	Search suggestions.
GET	/api/v1/search/stats	Search index statistics.

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

{"email": "admin@leocrm.local", "password": "secure-password"}

AuthResponse

{
  "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

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

UserResponse

{
  "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

{"status": "healthy", "version": "1.0.0"}

UnreadCountResponse

{"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.