Synaplan

https://docs.synaplan.com/
Admin
Synaplan is an open-source, self-hosted AI knowledge management platform with RAG, embeddable chat...
Tokens:197,118
Snippets:1,531
Trust Score:6.7
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### First production installation commands

Source: https://docs.synaplan.com/index.php/production

Run these commands in order to perform a first production installation. Copy the environment template, set required variables, then prepare, pull, validate, start, and smoke-test the stack. Leave both admin variables empty to use the first-run wizard at /setup.

```bash
cp deploy/selfhost.env.example deploy/.env
# Set SYNAPLAN_VERSION, the public URL, and BOOTSTRAP_ADMIN_*
# (or leave both admin vars empty and sign up later)
deploy/scripts/prepare.sh
docker compose --env-file deploy/.env -f deploy/compose.yaml pull
deploy/scripts/validate-release.sh
docker compose --env-file deploy/.env -f deploy/compose.yaml up -d
deploy/scripts/smoke-test.sh

```

--------------------------------

### GET /setup

Source: https://docs.synaplan.com/first-run-setup

Serves the setup wizard page when the instance has no administrator and no users. When the wizard is disabled, this route redirects to the login page.

```APIDOC
## GET /setup

### Description
Serves the setup wizard page when the instance has no administrator and no users. When the wizard is disabled, this route redirects to the login page.

### Method
GET

### Endpoint
/setup

### Response
#### Success Response (200)
- **html** (string) - The setup wizard page.

#### Redirect (302)
- **Location** (string) - The login page URL when the wizard is disabled.
```

--------------------------------

### Standard install with make up

Source: https://docs.synaplan.com/faq

Starts the standard stack (~4 GB) with cloud AI providers (OpenAI, Anthropic, Gemini, Groq, Mistral, xAI, TrustedTokens, A2Agent) plus file work and spoken answers. Add one API key and chat works.

```bash
make up
```

--------------------------------

### One-liner install command

Source: https://docs.synaplan.com/faq

Downloads and runs the official install script. Checks prerequisites, fetches and starts the standard stack (~4 GB).

```bash
curl -fsSL https://raw.githubusercontent.com/metadist/synaplan/main/install.sh | bash
```

--------------------------------

### Start compute sidecar with make up

Source: https://docs.synaplan.com/index.php/quickstart

Starts the compute sidecar with the app and file work enabled, or hides file work by setting COMPUTE_URL=disabled. Requires the repo's Compose setup, which builds the sidecar and runtimes, creates .compute-data/, injects a local token, and enables the feature.

```bash
make up                                       # app + file work + spoken answers
COMPUTE_URL=disabled make up                  # hide file work again

```

--------------------------------

### Start Docling sidecar with docker compose

Source: https://docs.synaplan.com/index.php/ai-infrastructure

Starts the Docling sidecar container with the docling profile. Requires about 4 GB of memory during OCR. The Compose setup injects DOCLING_BASE_URL as http://docling:5001.

```bash
docker compose --profile docling up -d
```

--------------------------------

### cURL examples for OAuth MCP connectors

Source: https://docs.synaplan.com/examples

These cURL examples demonstrate how to create an OAuth-based MCP server and start the browser sign-in flow.

```APIDOC
## POST /api/v1/mcp-servers

### Description
Creates a new MCP server row. For OAuth-based connectors like Notion and Higgsfield, this row must be created before starting the browser sign-in.

### Method
POST

### Endpoint
/api/v1/mcp-servers

### Parameters
#### Request Body
- **name** (string) - Required - The name of the MCP server (e.g., "Notion").
- **url** (string) - Required - The MCP server URL (e.g., "https://mcp.notion.com/mcp").
- **auth_mode** (string) - Required - The authentication mode; must be "oauth" for OAuth connectors.
- **enabled** (boolean) - Optional - Whether the server is enabled (default: true).
- **allow_write** (boolean) - Optional - Whether write operations are allowed (default: false).

### Request Example
{
  "name": "Notion",
  "url": "https://mcp.notion.com/mcp",
  "auth_mode": "oauth",
  "enabled": true,
  "allow_write": false
}

### Response
#### Success Response (200)
- **id** (integer) - The ID of the created server (used in subsequent OAuth start call).

#### Response Example
{
  "id": 42
}
```

```APIDOC
## POST /api/v1/mcp-servers/{id}/oauth/start

### Description
Starts the OAuth sign-in flow for an existing MCP server. After consent, Synaplan redirects to /channels/mcp?connected={id}.

### Method
POST

### Endpoint
/api/v1/mcp-servers/{id}/oauth/start

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the MCP server to authenticate.

### Request Example
(No request body)

### Response
#### Success Response (200)
- **authorize_url** (string) - The URL to open in the browser for user consent.

#### Response Example
{
  "authorize_url": "https://example.com/oauth/authorize"
}
```

--------------------------------

### Start services and wait for database

Source: https://docs.synaplan.com/faq

Start all services and wait 10 seconds for MariaDB to become ready.

```bash
make up && sleep 10
```

--------------------------------

### Reset setup wizard on dev stack

Source: https://docs.synaplan.com/first-run-setup

Run this command from the backend directory to delete all accounts and the completion flag, forcing the next page load to land on /setup. It only works when APP_ENV is dev or test, and the reset lasts only until the backend container restarts unless the stack is started with SEED_DEMO_DATA=false.

```bash
make -C backend setup-reset

```

--------------------------------

### Install Synaform plugin

Source: https://docs.synaplan.com/index.php/plugins

Install the Synaform plugin by cloning the repository, copying the plugin folder into the Synaplan plugins directory, clearing the cache, and installing the plugin for a specific user. Run these commands from the Synaplan root directory.

```bash
git clone https://github.com/metadist/Synaform.git
cp -r Synaform/synaform-plugin /path/to/synaplan/plugins/synaform
cd /path/to/synaplan
docker compose exec backend php bin/console cache:clear
docker compose exec backend php bin/console app:plugin:install <userId> synaform
```

--------------------------------

### Clone and start Synaplan with Docker Compose

Source: https://docs.synaplan.com/getting-started

Clone the Synaplan repository and start the stack with a single command. `make up` starts the status page on port 5173 first, then pulls all required images.

```bash
git clone https://github.com/metadist/synaplan.git
cd synaplan
make up

```

--------------------------------

### Install Synaplan and Triton from source

Source: https://docs.synaplan.com/index.php/kubernetes

Clones the synaplan-charts repository and installs the charts from source. Useful for development or testing with local chart changes.

```bash
git clone https://github.com/metadist/synaplan-charts.git
cd synaplan-charts
helm install synaplan ./charts/synaplan
helm install triton ./charts/triton

```

--------------------------------

### Install a Synaplan plugin via CLI

Source: https://docs.synaplan.com/index.php/plugins

Install a plugin by copying its directory into the Synaplan plugins folder, clearing the Symfony cache, and running the app:plugin:install command with the target user's ID. The cache:clear step is required so the new plugin is discovered.

```bash
# Copy the plugin directory into Synaplan
cp -r my-plugin/ /path/to/synaplan/plugins/my-plugin/

# Clear the Symfony cache so the new plugin is discovered
docker compose exec backend php bin/console cache:clear

# Install for a specific user (use the user's ID, e.g. 1 for the first admin)
docker compose exec backend php bin/console app:plugin:install <userId> my-plugin
```

--------------------------------

### Install Synaads plugin via git clone and console commands

Source: https://docs.synaplan.com/index.php/plugins

Install the Synaads plugin by cloning its repository, copying the plugin folder into the Synaplan plugins directory, clearing the cache, and running the plugin install command with the user ID. Requires Docker Compose and the Synaplan backend container.

```bash
git clone https://github.com/metadist/Synaads.git
cp -r Synaads/synaads-plugin /path/to/synaplan/plugins/synaads
cd /path/to/synaplan
docker compose exec backend php bin/console cache:clear
docker compose exec backend php bin/console app:plugin:install <userId> synaads

```

--------------------------------

### Full Configuration Example

Source: https://docs.synaplan.com/widget-api-reference.php

Full configuration example showing all common options: position, colors, theme, auto-open, auto-message, message limit, file upload settings, and lazy loading.

```html
<script type="module">
  import SynaplanWidget from 'https://web.synaplan.com/widget.js'

  SynaplanWidget.init({
    widgetId: 'wdg_095ab093966991158f9957f42ae8b4f2',
    position: 'bottom-right',
    primaryColor: '#13224e',
    iconColor: '#ffffff',
    defaultTheme: 'light',
    autoOpen: false,
    autoMessage: 'Hi! How can I help?',
    messageLimit: 50,
    allowFileUpload: true,
    fileUploadLimit: 3,
    maxFileSize: 10,
    lazy: true
  })
</script>
```

--------------------------------

### Copy .env.example to .env

Source: https://docs.synaplan.com/faq

Copies the template .env.example to .env in the backend directory. Run this before editing backend/.env with your own values; the file is git-ignored so credentials stay local.

```bash
cp backend/.env.example backend/.env

```

--------------------------------

### Complete Widget Configuration Example

Source: https://docs.synaplan.com/index.php/widget

Complete configuration example showing all common options: position, colors, theme, auto-open, auto-message, message limit, file upload settings, lazy loading, and a custom button icon URL. Use this as a template for a fully customized widget.

```html
<script type="module">
  import SynaplanWidget from 'https://web.synaplan.com/widget.js'

  SynaplanWidget.init({
    widgetId: 'wdg_095ab093966991158f9957f42ae8b4f2',
    position: 'bottom-right',
    primaryColor: '#13224e',
    iconColor: '#ffffff',
    defaultTheme: 'light',
    autoOpen: false,
    autoMessage: 'Hi! How can I help you today?',
    messageLimit: 50,
    maxFileSize: 10,
    allowFileUpload: false,
    fileUploadLimit: 3,
    lazy: true,
    buttonIconUrl: 'https://web.synaplan.com/api/v1/files/uploads/widget-icons/02/000/00002/2026/03/wicon_example.svg'
  })
</script>
```

--------------------------------

### SSO-only instance environment configuration

Source: https://docs.synaplan.com/first-run-setup

Environment variables to disable the setup wizard, registration, and guest chat, and to configure OIDC for an SSO-only instance. The database stays empty until the first sign-in, and AI provider keys are imported from the environment on start.

```plaintext
SETUP_WIZARD_ENABLED=false
REGISTRATION_ENABLED=false
GUEST_CHAT_ENABLED=false

OIDC_DISCOVERY_URL=https://idp.example.com/realms/main/.well-known/openid-configuration
OIDC_CLIENT_ID=synaplan
OIDC_CLIENT_SECRET=…
OIDC_AUTO_REDIRECT=true

```

--------------------------------

### Start the stack with make up

Source: https://docs.synaplan.com/index.php/modules/compute

Start the full stack on a laptop or single server (tier T1). Clones the repository, builds the compute sidecar and Python/Node runtimes, creates .compute-data/, injects a local token, and enables file work and workspaces. Do not publish port 8080.

```bash
git clone https://github.com/metadist/synaplan.git
cd synaplan
make up                     # app + file work + spoken answers

```

--------------------------------

### POST /api/v1/setup/admin

Source: https://docs.synaplan.com/first-run-setup

Creates the first administrator account during the setup wizard. This endpoint is only available when the setup wizard is enabled and no administrator or user exists. If the wizard is disabled, it returns a 409 error.

```APIDOC
## POST /api/v1/setup/admin

### Description
Creates the first administrator account during the setup wizard. This endpoint is only available when the setup wizard is enabled and no administrator or user exists. If the wizard is disabled, it returns a 409 error.

### Method
POST

### Endpoint
/api/v1/setup/admin

### Parameters
#### Request Body
- **email** (string) - Required - The email address for the administrator account.
- **password** (string) - Required - The password for the administrator account.

### Response
#### Success Response (200)
- **message** (string) - Confirmation that the administrator was created.

#### Error Response (409)
- **error** (string) - Error code `SETUP_WIZARD_DISABLED` indicating the wizard is disabled.

### Request Example
{
  "email": "admin@example.com",
  "password": "secret"
}

### Response Example
{
  "message": "Administrator created"
}
```

--------------------------------

### GET /api/v1/messages/history

Source: https://docs.synaplan.com/index.php/openapi

Get message history.

```APIDOC
## GET /api/v1/messages/history

### Description
Get message history.

### Method
GET

### Endpoint
/api/v1/messages/history
```

--------------------------------

### POST /api.php (action=wpWizardComplete)

Source: https://docs.synaplan.com/rest

Marks the WordPress onboarding wizard as complete.

```APIDOC
## POST /api.php (action=wpWizardComplete)

### Description
Complete the WordPress onboarding wizard.

### Method
POST

### Endpoint
/api.php

### Parameters
#### Form Data
- **action** (string) - Required - Must be `wpWizardComplete`.

### Request Example
curl -X POST -F "action=wpWizardComplete" https://web.synaplan.com/api.php

### Response
#### Success Response (200)
- Returns success status.

#### Response Example
{
  "success": true
}
```

--------------------------------

### GET /api/v1/realtime/subscribe

Source: https://docs.synaplan.com/index.php/openapi

Get Centrifugo subscription JWT.

```APIDOC
## GET /api/v1/realtime/subscribe

### Description
Get Centrifugo subscription JWT.

### Method
GET

### Endpoint
/api/v1/realtime/subscribe
```

--------------------------------

### GET /api/v1/realtime/token

Source: https://docs.synaplan.com/index.php/openapi

Get Centrifugo connection JWT.

```APIDOC
## GET /api/v1/realtime/token

### Description
Get Centrifugo connection JWT.

### Method
GET

### Endpoint
/api/v1/realtime/token
```
Tokens:
Raw