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.3 / Symfony 7 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), cloud integrations (Nextcloud, OpenCloud), and the Outlook add-in (Synamail).

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

Last updated: June 2026

30-Second Quickstart

Pick your entry point:

What's New

MCP Server (early access)

Synaplan now speaks the Model Context Protocol. 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. The first release ships read-only knowledge tools (rag_search, memory_search) over the Streamable HTTP transport; more tools are on the way. See MCP Server.

Multi-Task Routing

Complex requests are no longer limited to a single AI call. An AI planner can decompose a message into a task graph — extract text → summarize → generate audio → compose reply — and execute the steps while live task cards stream into the chat UI. A single request can now deliver multiple generated files, on every channel (chat, widget, WhatsApp, email, webhooks). See Architecture & Realtime.

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:

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 cloud platforms so your existing files become AI knowledge sources — and we maintain dedicated open-source integration repos for each:

• Nextcloud — metadist/synaplan-nextcloud: run your own AI platform next to Nextcloud for RAG-powered discussions, translations, and summaries.
• OpenCloud (ownCloud Infinite Scale) — metadist/synaplan-opencloud: full support for the OpenCloud / oCIS WebDAV and Graph API.

Both integrations support automatic re-indexing when files change, and documents are processed through the same OCR and text extraction pipeline used by the rest of the platform.

AI Models

Synaplan ships a curated catalog of models from every major provider, plus self-hosted options. You pick a different model per task (chat, vision/OCR, image, video, audio, embeddings) per user — configurable in the admin panel under System Config → AI Models.

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 June 2026 snapshot if the live catalog can't be reached):

Chat & vision (LLMs)

Media, audio & embeddings

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

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.

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, Groq, and Google Gemini — pick a different model per task.
• Multi-Task Routing: An AI planner decomposes complex requests into task graphs with live progress streaming.
• RAG System: Document processing with OCR, vectorization (bge-m3), and semantic search via MariaDB VECTOR or Qdrant.
• 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 and OpenCloud as knowledge sources.
• OpenAI Compatibility: Drop-in endpoints for chat completions, image generation, and audio transcription.
• MCP Server: 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.

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 and legacy REST endpoints.
   • You can create and manage API keys in the Settings > API Keys section of the app.

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
• Legacy REST: https://web.synaplan.com/api.php
• OpenAI-compatible: https://web.synaplan.com/api.php/v1/...

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 from the Synaplan dashboard under Widgets. See the Widget Integration page for all configuration options.

Documentation Sections