Welcome to Synaplan

Synaplan is an open-source, self-hosted AI knowledge management platform with RAG, embeddable chat widgets, plugins, cloud integrations, and multi-channel AI. Built with PHP 8.4 / Symfony 8 and Vue 3 / TypeScript.

This is the developer & user documentation. It covers everything you can build with Synaplan — not just the API: the embeddable chat widget, the plugin ecosystem (Synaads, Synaform 4.x), cloud integrations (Nextcloud, OpenCloud, ownCloud.online), the Outlook add-in (Synamail), and Synaplan Desktop (pair a computer and run local Agent Skills).

Live instance: web.synaplan.com  |  Source: github.com/metadist/synaplan  |  All repos: github.com/orgs/metadist

Last updated: September 2026

30-Second Quickstart

Pick your entry point:

What's New

4.8 — one home per concept, everything on by default (September 2026)

• Every September feature is on out of the box. People & groups, sharing, assistants, export & import, tools & approvals, custom HTTP tools, the saved-task Steps editor, Synaplan Desktop pairing and linked platforms all seed on; upgrading installs are switched on by a migration. Operators turn any of them off under Operate → System configuration → Features or pin them per deployment with FEATURE_<GROUP>_<SETTING>=false. Only file work (COMPUTE.*) stays off until a sidecar is connected. Reference: Administration → Feature flags.
• The menu was consolidated. Manage now has five groups — Assistants, Automations, Channels, Connections, Developer & devices — so API keys, API docs, Coding clients and Desktop sit together, and Connected apps (mailboxes, folders, calendars, custom tools) is visible to every signed-in user. Operate → People is the only home for users; the old Users tab redirects there.
• Summarize a document runs in the chat. The separate Summarizer page is retired; Tools → Summarize a document attaches a file and answers in the thread.
• All chats (/chats) is the searchable archive with an Incoming tab for chats shared with you; Account → Usage shows usage only.
• Your AI accounts (Manage → Assistants → Your AI accounts) holds your personal Higgsfield credentials and your own Anthropic key for Claude Code. For the instance, Operate → AI infrastructure → Models & keys is the one web editor for provider keys.
• Saved tasks grew up: a Steps editor (tool step, condition, outbound webhook, ask-before-run), a webhook trigger, task templates, and step-by-step progress narration in chat. See Tools & approvals and Multi-Task Routing.
• New providers: A2Agent 🇨🇳 (Qwen3.8, DeepSeek V4, MiniMax M3) joins the catalog, Google adds speech-to-text, and Perplexity is an optional chat provider.

File work (secure compute, September 2026)

The assistant can run a short Python or Node program on copies of files you picked and hand the result back as files — off until an operator starts the sidecar and switches COMPUTE.ENABLED on. Developers: the compute Compose profile. Production: a dedicated gVisor box, never the web nodes. See Secure compute and Run the compute sidecar.

Tools, approvals and a fuller assistant builder (September 2026)

• Tools & approvals — one tool registry, write-class actions that wait for you in chat and under Manage → Automations → Approvals, and custom HTTP / OpenAPI tools on Manage → Connections → Connected apps. All on by default since 4.8. See Tools & approvals.
• Assistants now include knowledge folders you already share, tools and skills, triggers (mail rules, schedules, widget / WhatsApp / API / Desktop), and Export & import (BUNDLE.ENABLED). See Assistants.

Assistants, pluggable AI infrastructure, watched pages (September 2026)

• Assistants — a saved recipe of instructions, models, knowledge, tools and triggers that its owner publishes in versions to a group or everyone; users always talk to the current published version and can clone it (AGENTS.ENABLED, on since 4.8). See Assistants.
• AI infrastructure — Operate → AI infrastructure swaps the services behind the AI without code changes: an optional Docling extractor that keeps tables intact, web search via Brave, self-hosted SearXNG, Tavily, Exa, Firecrawl or Perplexity, an eval-gated rerank stage, and Import models from any OpenAI-compatible endpoint or Ollama. Plugins can add their own adapters. See AI infrastructure.
• Watched pages — "get this URL, save it, compare it to the last version and mail me the differences", saved as a daily task, mails a diff whenever a page changes. See Multi-Task Routing → Watched pages.
• Chat that holds up — an answer keeps streaming after a reload or on another device (Still answering), long pastes collapse into an editable card, and a failing provider offers Try again with another model instead of a raw error. Routing is schema-enforced and self-healing. See Using Synaplan.
• Android app on Google Play next to the iPhone app; French UI and TTS voice.

People & groups, then team sharing (September 2026)

Named teams on one instance. Operate → People manages users, groups, per-group policies and the audit trail. Sharing a folder, chat, assistant, saved task or widget with a person or group (IAM.SHARING_ENABLED, on since 4.8): Can view opens the item; Can use lets the AI search those files and lets you Continue as my copy. Ownership never moves; admins do not see private content unless it is shared with them. Details: People & groups.

Synaplan Desktop (public beta, September 2026)

Pair a Windows, macOS, or Linux computer with your workspace: chat from a native window and run bundled Agent Skills that create files locally (slides, invoices, charts, email drafts, calendar invites) under a folder allowlist. No shell, scoped pairing key in the OS secret store. Pairing lives under Manage → Developer & devices → Desktop and is on by default. See Synaplan Desktop.

Onboarding & install (August 2026)

• Guided first start — docker compose up -d now serves a live status screen at http://localhost:5173 within seconds: it shows every boot step (database, backend, optional AI model download, interface) and switches into the app automatically the moment it is ready. The same notes print in docker compose logs -f startup-notes.
• One-line installer — curl -fsSL https://raw.githubusercontent.com/metadist/synaplan/main/install.sh | bash checks prerequisites, fetches the stack, and starts it. The default stack is cloud-AI only (~3 GB); COMPOSE_PROFILES=local-ai adds Ollama; --mode server sets up a production server including .env generation with auto-created secrets. Details in Quickstart & Self-Hosting.
• Demo mode with a way out — until an AI provider is connected, chat answers with clearly-labeled demo replies that carry a Go to AI provider setup button. One API key (free options available) — or a local Ollama with a capable model, no key at all — switches to real AI instantly, no restart needed.
• These docs got a refresh — task-oriented navigation, a mobile-friendly layout, and new pages for getting started, production deployment, Kubernetes, and administration.

Ecosystem extras (July 2026)

• TrustedTokens 🇩🇪 — new sovereign provider: GLM 5.2, Qwen3.6 35B and GPT OSS 120B served from GPUs in Munich. Together with Anthropic's Claude Opus 5 / Sonnet 5 and the retirement of the older Claude generations, see AI Models below.
• ownCloud.online — new integration for BW-Tech ownCloud.online (oco_synaplan). Always write the brand as ownCloud.online, not “ownCloud” alone. Separate from OpenCloud / oCIS. See Plugins & Integrations.
• Nextcloud Integration — updated app (Nextcloud 30–34): Research Chat with streaming, memories, /pic · /vid, DAG routing, and Admin Settings → Synaplan Integration.
• Synamail — generally available Outlook add-in with an updated taskpane: Contact AI Profiling, Writing assistant in compose, AppSource or self-host. See Outlook Add-in (Synamail).
• Synaform 4.x — stronger AI extraction into standard Word / form templates, AI field assist, editable prompts, Collection-first UX.

MCP in both directions (early access)

Synaplan now speaks the Model Context Protocol — both ways. As a server, point an MCP host — Claude, Cursor, VS Code, or any compatible client — at https://web.synaplan.com/mcp with your API key, and your knowledge base and memories become tools the model can call directly. As an outbound client, connect your MCP servers (a CRM, a wiki, an n8n endpoint, or hosted servers such as Notion and Higgsfield) under Manage → Connections → MCP Servers, and the multi-task planner can pull live data from them into an answer — and, when you allow write actions on a server, create tickets or pages, with destructive tools always refused. Per user, per assistant. See MCP — Server & Client.

Multi-Task (DAG) Routing

Complex requests are no longer limited to a single AI call. An AI planner can decompose a message into a DAG of tasks — extract text → summarize → generate audio → compose reply — and execute the steps in dependency order while live task cards stream into the chat UI. A single request can now deliver multiple generated files (text, media, documents, even an .ics calendar invite), on every channel (chat, widget, WhatsApp, email, webhooks). See Multi-Task (DAG) Routing.

Realtime & Live Support

Synaplan now ships a WebSocket layer built on Centrifugo + Redis: operators can take over widget conversations from the AI in real time, with typing indicators in both directions and instant operator notifications. Browsers connect same-origin via /connection/websocket — no CORS setup. A dedicated background worker container executes async jobs from Redis-backed queues. Full picture: Architecture & Realtime.

Plugin Ecosystem

Synaplan supports a non-invasive plugin architecture — drop a plugin into the plugins/ folder, run one install command, and it appears in the sidebar with no changes to core code. Each plugin is open source and lives in its own repository:

The optional office engine (Collabora CODE sidecar) is not a plugin. It is a compose profile — see Office documents — next to TTS: off by default, required only for PDF export, office thumbnails, preview and conversion. Collabora never sees Synaplan users; convert-to is server-to-server.

Plugins expose their own API endpoints under /api/v1/user/{userId}/plugins/{name}/.... See the Plugins & Integrations page for full details.

Cloud Storage Integrations

Synaplan connects to self-hosted and managed cloud platforms so your existing files become AI knowledge sources — each with its own open-source integration repo:

• Nextcloud — metadist/synaplan-nextcloud: summarize, translate, index, and research-chat over Nextcloud files (App Store: Synaplan Integration).
• OpenCloud (ownCloud Infinite Scale / oCIS) — metadist/synaplan-opencloud: WebDAV and Graph API, Spaces-aware indexing.
• ownCloud.online — metadist/synaplan-owncloud-online: the same AI actions inside BW-Tech ownCloud.online (classic PHP stack). Use the full brand name ownCloud.online.

All three share Synaplan's OCR / text-extraction and RAG pipeline and re-index when files change.

AI Models

Synaplan ships a curated catalog of models from every major provider, plus self-hosted and EU-sovereign options. You pick a different model per task (chat, vision/OCR, image, video, audio, embeddings) per user under Manage → Assistants → Models (/ai/models); administrators curate the catalog and prices on the same page.

Providers you can enable with one key each: OpenAI, Anthropic, Google Gemini, Groq, Mistral 🇫🇷, xAI, TrustedTokens 🇩🇪, A2Agent 🇨🇳, HuggingFace, TheHive, Higgsfield, Cloudflare Workers AI, optional Perplexity — plus Ollama and Piper running on your own hardware with no key and no per-token cost. See the Developer FAQ for the variable names and what each key unlocks.

New in July 2026: TrustedTokens (TNG Technology Consulting) joins the catalog — GLM 5.2, Qwen3.6 35B and GPT OSS 120B served from GPUs in Munich under German jurisdiction, with zero data retention. Anthropic's line moved to Claude Opus 5 and Claude Sonnet 5; the Opus 4.1–4.7 and Sonnet 4.5/4.6 generations were retired and existing defaults repointed automatically.

The table below is generated live from the running platform whenever possible, so it always reflects what's actually enabled (it falls back to a curated July 2026 snapshot if the live catalog can't be reached):

Chat & vision (LLMs)

Media, audio & embeddings

Live from web.synaplan.com · 96 models · updated 2026-06-07 11:51 UTC

Prices are the provider's own rates, in USD per 1M tokens — Synaplan does not resell them through a proprietary credit unit. In the app, every model in the selector (and on every answer) carries a Free / Low / Mid / High cost badge derived from these numbers, and the Usage page (Account → Usage; administrators see everyone on the Usage tab of Operate → Overview) logs the real cost of each call. On web.synaplan.com that same catalog is what your plan meters against. See Model pricing & cost transparency in the FAQ.

Always-current list: the catalog evolves with each release. For the live, authoritative list of models enabled on an instance, call GET /api/v1/models with your API key (see Code Examples) or open the model selector in the app. GET /api/v1/config/models additionally returns priceIn / priceOut per model.

Synaplan is an AI-powered knowledge management system that provides a robust API for integrating AI capabilities into your applications. Whether you're building a custom chatbot, automating document processing, or integrating with multi-channel communication (WhatsApp, Email), the Synaplan API provides the tools you need.

Core Features

• AI Chat: Talk to Ollama (local), OpenAI, Anthropic, Google Gemini, Groq, Mistral, xAI, TrustedTokens (Germany), A2Agent (China) and HuggingFace — pick a different model per task, with the price of each one visible before you choose.
• Multi-Task (DAG) Routing: An AI planner decomposes complex requests into a DAG of tasks with live progress streaming and multiple generated files per request.
• Assistants: Saved recipes of instructions, models, knowledge, tools and triggers, published in versions to a group or the whole instance.
• Tools & approvals: One registry of callables; write-class actions wait in chat and under Manage → Automations → Approvals. Custom HTTP / OpenAPI tools live on Connected apps.
• Saved tasks: Pin a plan, run it on a schedule, a webhook or on demand; edit its Steps; copy it as a template. Unattended write actions pause for approval.
• RAG System: Document processing with OCR, vectorization (bge-m3), and semantic search via MariaDB VECTOR or Qdrant — with pluggable extraction, web search and reranking.
• Multi-Channel AI: Web chat widgets, WhatsApp (Meta Business API), and Email integrations.
• Live Support: Realtime human takeover of widget chats via WebSockets (Centrifugo + Redis).
• Audio: Whisper transcription (speech-to-text) plus optional Text-to-Speech voice output.
• AI Memories & Feedback: User profiling and learning powered by Qdrant vector search.
• Plugin Ecosystem: Extend the platform with open-source plugins (Synaads, Synaform) — no core code changes.
• Cloud Integrations: Index files from Nextcloud, OpenCloud, and ownCloud.online as knowledge sources.
• OpenAI Compatibility: Drop-in endpoints for chat completions, image generation, and audio transcription.
• Claude Code / Anthropic Compatibility: An Anthropic-compatible Messages API gateway at POST /v1/messages — run Claude Code against your Synaplan instance with BYO or operator keys, budget metering, and per-session summary chats.
• MCP Server & Client: Connect AI clients (Claude, Cursor, …) to Synaplan over the Model Context Protocol — your knowledge base and memories become tools, with one URL and one API key. And in the other direction, connect your MCP servers as live data sources for the multi-task planner.

Authentication

Synaplan uses a secure token-based authentication system:

1. API Key (Recommended for API integration)

   • Send the header: Authorization: Bearer YOUR_API_KEY or X-API-Key: YOUR_API_KEY
   • Works with all /api/v1/ endpoints, the /v1 OpenAI- and Anthropic-compatible gateways, /mcp, and the legacy api.php shim.
   • You can create and manage API keys under Manage → Developer & devices → API Keys (/channels/api). Keys can be scoped (for example iam:read, compute:run, desktop:*); a key without scopes keeps full access.

2. Session Cookies (For Browser-based apps)

   • Used by the main frontend application.
   • Implements an Access Token + Refresh Token system with OIDC/Keycloak support.

3. SSE Tokens (For Streaming)

   • Since EventSource cannot send custom headers, a short-lived token can be passed via a query parameter: ?token=YOUR_SSE_TOKEN.
   • Obtain this token via the /api/v1/auth/token endpoint.

4. Realtime Tokens (For WebSockets)

   • Live-support features (chat takeover, typing indicators) use WebSockets via Centrifugo.
   • The backend mints short-lived connection and subscription JWTs via /api/v1/realtime/token and /api/v1/realtime/subscribe — see Architecture & Realtime.

5. Anonymous widget session

   • Initialize via widget loader, then call REST endpoints with the same cookie jar.

Base URL

The API is available at the following base URL:

• Production: https://web.synaplan.com/api/v1
• Development: http://localhost:8000/api/v1
• OpenAI-compatible: https://web.synaplan.com/v1 (/v1/chat/completions, /v1/models, /v1/audio/transcriptions)
• Anthropic-compatible (Claude Code): https://web.synaplan.com/v1/messages
• MCP server: https://web.synaplan.com/mcp
• Legacy REST shim: https://web.synaplan.com/api.php (a handful of 1.x actions — see REST Architecture)

Interactive Documentation

The most up-to-date and interactive documentation (Swagger UI) is available at:

https://web.synaplan.com/api/doc

Quick Start: Using the API with cURL

Here is how you can quickly test your API key by fetching your profile information:

curl -X GET "https://web.synaplan.com/api/v1/auth/me" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Accept: application/json"

Quick Start: Embed the Widget

Add the chat widget to any website with a single ES module import:

<script type="module">
  import SynaplanWidget from 'https://web.synaplan.com/widget.js'
  SynaplanWidget.init({ widgetId: 'YOUR_WIDGET_ID' })
</script>

Get your widgetId under Manage → Channels → Chat widgets. See the Widget Integration page for all configuration options.

Documentation Sections

Getting started

Install & self-host

Using Synaplan

Chat widget

Channels & integrations

Synaplan Desktop

Administration

Feature modules

Developers