leocrm/docs/api-documentation.md

LeoCRM API Documentation

Auto-generated from FastAPI route enumeration. 303 endpoints across 31 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 (6 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
GET	/api/v1/system-settings/backup-config	Get backup configuration (backup_enabled, backup_interval, backup_retention_days, backup_destination).
PUT	/api/v1/system-settings/backup-config	Update backup configuration. Admin only.
POST	/api/v1/system-settings/backup-now	Trigger an immediate backup via ARQ job. Admin only. Returns {"message": "Backup job enqueued", "job_id": "..."}.
GET	/api/v1/system-settings/backup-history	Get last 10 backup results from audit log. Returns {"history": [...]}.

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 (4 endpoints)

Method	Path	Description
GET	/api/v1/audit-log	Query audit log entries (filterable, paginated, admin-only).
GET	/api/v1/audit-log/export	Export audit log as CSV or JSON (streaming, max 10.000 entries). Query: format (csv/json), entity_type, action, date_from, date_to
DELETE	/api/v1/audit-log/retention	Delete audit log entries older than retention_days (default 365, admin-only). Query: retention_days (1-3650)

system (2 endpoints)

Method	Path	Description
GET	/api/v1/system/dashboard	Comprehensive system dashboard (admin-only). Returns: health, DB stats, Redis stats, worker stats, API stats, plugin stats, storage stats.
GET	/api/v1/system/alerts	Active system alerts (admin-only). Returns alerts from Communication-System.

---

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)

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

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

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

---

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.

---

Phase H — Knowledge Endpoints

Wiki (H-WIKI, H-VER, H-LINK)

Method	Path	Description	Permission
GET	/api/v1/wiki/articles	List articles (paginated, filterable)	wiki:read
POST	/api/v1/wiki/articles	Create article	wiki:write
GET	/api/v1/wiki/articles/{id}	Get article by ID	wiki:read
PATCH	/api/v1/wiki/articles/{id}	Update article (creates version)	wiki:write
DELETE	/api/v1/wiki/articles/{id}	Delete article (soft-delete)	wiki:delete
GET	/api/v1/wiki/articles/{id}/versions	List article versions	wiki:read
POST	/api/v1/wiki/articles/{id}/versions/{version}/restore	Restore article to version	wiki:write
GET	/api/v1/wiki/categories	List categories	wiki:read
POST	/api/v1/wiki/categories	Create category	wiki:write

Knowledge Sources (H-SRC)

4 source types: wiki, dms, mail, communication. Each provides content for RAG indexing via fetch_source_content().

Evidence References (H-CITE)

RAG/Knowledge results include structured EvidenceReference objects with:

• source_type, source_id, title, url (deep link)
• snippet, confidence, metadata
• to_workstream_block() for Communication display

Knowledge Extraction (H-EXT, H-ENT, H-AUTO, H-CONF)

• extract_knowledge(): LLM-based entity and relationship extraction
• auto_create_relationships(): Creates high-confidence relationships in GraphRAG
• Confidence threshold: 0.6 (low-confidence → review queue)
• Entity types: person, company, project, location, date, other
• Relationship types: works_for, related_to, has_email, part_of, etc.

Knowledge Lifecycle (H-EVT, H-DATA-LIFE, H-RET)

• Event triggers: mail.received, dms.file_uploaded, wiki.article_published, communication.message_created
• Derived-data lifecycle: Source deletion/correction propagates to graph relationships and agent memory
• Retention policy: wiki=unlimited, dms=365d, mail=180d, communication=90d
• Cleanup: ARQ cron job removes expired knowledge

Ask Knowledge (H-ASK)

RAG queries with evidence cards via workstream. Returns answer + evidence references + workstream blocks.

Review Queue (H-REV)

Low-confidence extracted relationships pending human review. Approve boosts confidence to 0.8, reject deletes.