Synaplan API - Introduction

Synaplan is an open-source, self-hosted AI knowledge management platform with RAG, embeddable chat widgets, and multi-channel integration. Built with PHP 8.3 / Symfony 7 and Vue 3 / TypeScript.

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

What's New

Plugin System

Synaplan now supports a non-invasive plugin architecture. Plugins live under plugins/ in the main repo and integrate through generic data tables — no core code changes required.

Plugins are installed per-user via the CLI and expose their own API endpoints under /api/v1/user/{userId}/plugins/{name}/.... See the Plugins & Integrations page for details.

Cloud Storage Integrations

Synaplan integrates with popular self-hosted cloud platforms for document indexing and RAG:

• Nextcloud — Connect your Nextcloud instance to index documents, sync folders, and use them as knowledge sources for AI conversations.
• OpenCloud (ownCloud Infinite Scale) — Full support for the OpenCloud / oCIS WebDAV and Graph API, enabling seamless file access and document-based RAG pipelines.

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.

Updated AI Models

The platform supports the latest models from all major providers:

Model selection is per-user and configurable in the admin panel. You can set different models for chat, vision/OCR, embeddings, and image generation.

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

• RAG System: Document processing, vectorization (bge-m3), and semantic search with MariaDB VECTOR.
• Multi-Channel AI: Support for Web chat widgets, WhatsApp, and Email integrations.
• Plugin Architecture: Extend the platform's capabilities with custom plugins.
• OpenAI Compatibility: Standard endpoints for chat completions, image generation, and more.
• MCP Integration: (Planned) Support for the Model Context Protocol to bridge tools and AI.

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