### 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
```

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

### 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>
```

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

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

```

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

### 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"
}
```

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

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

```

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

### 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>
```

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

### Install Synaads plugin via git clone and Docker

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

Install Synaads like any Synaplan plugin. Clone the repository, copy the plugin directory, then clear the cache and install the plugin using Docker Compose commands. Replace <userId> with the actual user ID.

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

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

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

```

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

### 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 bundled Collabora sidecar with docker compose

Source: https://docs.synaplan.com/index.php/office-documents

Starts the bundled Collabora sidecar using the office profile. The deploy entrypoint sets OFFICE_CONVERT_URL=http://collabora:9980 when the office profile is active.

```bash
docker compose --env-file deploy/.env -f deploy/compose.yaml --profile office up -d

```

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

### Start SearXNG sidecar with Docker Compose

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

Starts the SearXNG sidecar using the developer/evaluation stack. The service has no published host port; only the backend and worker reach it on the Compose network.

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

```

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

### Start Docling sidecar with Docker Compose profile

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

Starts the Docling sidecar in the developer/evaluation stack. The docker-compose.yml ships a docling profile with the CPU image, about 4.4 GB to pull and up to 4 GB of RAM during OCR.

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

```

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

### Production install with install.sh --mode server

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

Installs the production mode on a Linux server using the published image. See Production Deployment for details.

```bash
install.sh --mode server
```

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

### Disable setup wizard with SETUP_WIZARD_ENABLED=false

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

Set this environment variable to false to disable the setup wizard. When unset or empty, it defaults to true, keeping the wizard enabled. With false, /setup redirects to login, POST /api/v1/setup/admin returns 409 SETUP_WIZARD_DISABLED, and the API serves requests normally even with an empty user table.

```plaintext
SETUP_WIZARD_ENABLED=false

```

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

### cURL: create server row and start OAuth sign-in

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

Commands to create a server row and start the OAuth sign-in flow. Requires MCP.OAUTH_CONNECTORS_ENABLED=1. After consent, Synaplan redirects to /channels/mcp?connected=42.

```bash
# Requires MCP.OAUTH_CONNECTORS_ENABLED=1 on the installation.
curl -X POST "https://web.synaplan.com/api/v1/mcp-servers" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name":"Notion","url":"https://mcp.notion.com/mcp","auth_mode":"oauth"}'

curl -X POST "https://web.synaplan.com/api/v1/mcp-servers/42/oauth/start" \
     -H "Authorization: Bearer YOUR_API_KEY"

# Open authorize_url in the browser. After consent, Synaplan redirects to
# /channels/mcp?connected=42
```

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

### Install Synaplan and Triton from GHCR

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

Installs the stable Synaplan and Triton charts from GHCR as OCI artifacts. Use for production deployments; stable releases are immutable.

```bash
# Stable release (recommended for production)
helm install synaplan oci://ghcr.io/metadist/synaplan-charts/synaplan --version 0.1.0
helm install triton oci://ghcr.io/metadist/synaplan-charts/triton --version 0.1.0

```

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

### Start Ollama with local-ai profile

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

Starts the local-ai Compose profile for Ollama, pulling the bge-m3 embeddings model (~1 GB) in the background. Add ENABLE_LOCAL_GPT_OSS=true to also pull gpt-oss:20b for local chat (~14 GB, GPU or strong CPU recommended).

```bash
COMPOSE_PROFILES=local-ai make up

```

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

### Start TTS in the minimal stack with the tts profile

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

Starts the TTS service in the minimal stack, which keeps TTS opt-in via the `tts` profile.

```bash
docker compose -f docker-compose-minimal.yml --profile tts up -d

```

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

### Install Synaplan and Triton from GHCR

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

Installs the stable release of the synaplan and triton charts from the GitHub Container Registry. Requires Kubernetes 1.24+, Helm 3.14+, and kubectl configured. Stable releases are immutable and created from git tags.

```bash
# Stable release (recommended for production)
helm install synaplan oci://ghcr.io/metadist/synaplan-charts/synaplan --version 0.1.0
helm install triton oci://ghcr.io/metadist/synaplan-charts/triton --version 0.1.0
```

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

### Start Office profile with Docker Compose

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

Starts the Docker Compose stack with the 'office' profile, enabling the Collabora CODE sidecar for Office document features. The profile is off by default to avoid extra RAM usage and pulling the collabora/code image.

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

```

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

### Self-host with Docker

Source: https://docs.synaplan.com/presentation-developers.html?lang=en

Commands to clone the Synaplan repository and start it with Docker Compose for self-hosting.

```bash
git clone github.com/metadist/synaplan
cd synaplan
docker compose up -d
```

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

### Install with local AI profile

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

Adds Ollama and the bge-m3 embedding model on your own hardware (~5 GB). Setting ENABLE_LOCAL_GPT_OSS=true also pulls a local chat model (+~14 GB).

```bash
COMPOSE_PROFILES=local-ai make up
```

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

### Start TTS service

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

Start the TTS service either with the stack using `make up` or standalone with Docker. The standalone command runs the container on port 10200 and uses the image `ghcr.io/metadist/synaplan-tts:latest`.

```bash
make up                 # the tts service starts with the stack
# or, standalone on this host / another machine:
docker run -d --name synaplan-tts -p 127.0.0.1:10200:10200 \
  ghcr.io/metadist/synaplan-tts:latest
```

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

### Enable with the stack: make up and docker compose stop

Source: https://docs.synaplan.com/index.php/modules/piper-tts

Commands to start the development/evaluation stack with the TTS service and to stop it. The standard compose files start the published image and default SYNAPLAN_TTS_URL to http://tts:10200.

```bash
make up                     # dev / evaluation stack: tts starts with it
docker compose stop tts     # hide spoken answers again
```

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

### REST API start OAuth sign-in

Source: https://docs.synaplan.com/index.php/mcp-oauth

Curl command to start OAuth sign-in for an MCP server row. The response includes an authorize_url to send the browser to. The provider redirects to the callback endpoint, which then redirects to /channels/mcp?connected=42.

```bash
# After the server row exists:
curl -X POST "https://web.synaplan.com/api/v1/mcp-servers/42/oauth/start" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json"

# → { "success": true, "authorize_url": "https://mcp.notion.com/authorize?…" }
# Send the browser to authorize_url. The provider redirects to:
#   /api/v1/mcp-servers/oauth/callback?code=…&state=…
# which then redirects to /channels/mcp?connected=42
```

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

### GET /api/v1/tools

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

Manage tools.

```APIDOC
## GET /api/v1/tools

### Description
Manage tools.

### Method
GET

### Endpoint
/api/v1/tools
```

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

### manifest.json example

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

Example manifest.json for a plugin. The provides.resourceKinds field is optional; each key must be {pluginId}:{name} and permissions are a subset of read, use, edit, manage. An invalid field stops the plugin from loading and names the field.

```json
{
  "id": "my-plugin",
  "name": "my-plugin",
  "namespace": "Plugin\\MyPlugin",
  "version": "1.0.0",
  "displayName": "My Plugin",
  "description": "Short description of what the plugin does",
  "author": "Your Name",
  "capabilities": ["api", "frontend", "migrations"],
  "config": { "group": "P_myplugin" },
  "provides": {
    "resourceKinds": [
      {
        "key": "my-plugin:form",
        "dataType": "form",
        "labelKey": "myplugin.kind.form",
        "permissions": ["read", "use", "edit"]
      }
    ]
  }
}

```

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

### Enable with minimal stack: docker compose --profile tts

Source: https://docs.synaplan.com/index.php/modules/piper-tts

Command to start the minimal stack with the TTS service using the opt-in profile.

```bash
docker compose -f docker-compose-minimal.yml --profile tts up -d     # minimal stack
```

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

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

```

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

### Clone and run synaplan-tts with Docker Compose

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

Clones the synaplan-tts repository and starts it with Docker Compose. This is an alternative to the standalone `docker run` command.

```bash
git clone https://github.com/metadist/synaplan-tts.git
cd synaplan-tts
docker compose up -d

```

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

### 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
```

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

### Use host Ollama base URL

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

Points the backend at an Ollama instance already running on the host, skipping the container. Use this instead of the default container-based setup.

```plaintext
OLLAMA_BASE_URL=http://host.docker.internal:11434

```

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

### 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
```

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

### GET /api/v1/auth/token

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

Get a short-lived SSE token.

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

### Description
Get a short-lived SSE token.

### Method
GET

### Endpoint
/api/v1/auth/token
```

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

### GET /api/v1/groups/mine

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

Get groups belonging to the current user.

```APIDOC
## GET /api/v1/groups/mine

### Description
Get groups belonging to the current user.

### Method
GET

### Endpoint
/api/v1/groups/mine
```

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

### GET /api/v1/auth/me

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

Get current authenticated user information.

```APIDOC
## GET /api/v1/auth/me

### Description
Get current authenticated user information.

### Method
GET

### Endpoint
/api/v1/auth/me
```

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

### Start and stop TTS with the standard stack

Source: https://docs.synaplan.com/modules/piper-tts

Starts the standard dev/evaluation stack with the TTS service, and stops the TTS container to hide spoken answers. The standard compose files start the published image and default SYNAPLAN_TTS_URL to http://tts:10200.

```bash
make up                     # dev / evaluation stack: tts starts with it
docker compose stop tts     # hide spoken answers again

```

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

### Start Collabora sidecar with office profile

Source: https://docs.synaplan.com/index.php/office-documents

Run the office compose profile so Collabora is available for convert-to. A plain `make up` does not pull the image or use the extra ~2 GB RAM. Compose defaults OFFICE_CONVERT_URL to http://collabora:9980, and the backend cannot override it in backend/.env.

```bash
cd synaplan
docker compose --profile office up -d

```

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

### SynaplanWidget.init({ widgetId: 'wdg_...' })

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

Initializes the Synaplan widget with the given configuration. This must be called before using other methods.

```APIDOC
## SynaplanWidget.init({ widgetId: 'wdg_...' })

### Description
Initializes the Synaplan widget with the given configuration. This must be called before using other methods.

### Method
init

### Parameters
- **widgetId** (string) - Required - The widget ID, typically in the format 'wdg_...'.

### Request Example
```javascript
SynaplanWidget.init({ widgetId: 'wdg_...' })
```

### Response
No return value documented.
```

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

### Start and stop the TTS service

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

Starts the TTS service with the stack using make up, and stops it with docker compose stop tts to disable spoken answers.

```bash
make up                   # the tts service starts with the stack

```

```bash
docker compose stop tts     # hide spoken answers again

```

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

### Enable compute profile in deploy/.env

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

Enable the compute profile for a single production host by adding 'compute' to COMPOSE_PROFILES in deploy/.env and redeploying. prepare.sh writes the token and the stack exports the URL and enable flags.

```bash
COMPOSE_PROFILES=compute    # or compute,office — in deploy/.env, then redeploy

```

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

### Clone and run Synamail from source

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

Commands to clone and run the Synamail add-in from source. Use `make bootstrap` to set up hooks and dependencies, `make doctor` to verify the toolchain, `make ci-local` for linting, type-checking, tests, manifest validation, and build, `make dev` to serve the taskpane locally, and `make sideload` to register the manifest into Outlook.

```bash
git clone https://github.com/metadist/Synamail.git
cd Synamail
make bootstrap     # enable git hooks + install deps
make doctor        # verify your toolchain
make ci-local      # lint + type-check + tests + manifest validate + build
make dev           # serve the taskpane on https://localhost:3000
make sideload      # register the manifest into Outlook
```

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

### Enable local AI with COMPOSE_PROFILES=local-ai

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

Opt-in Compose profiles for local AI. The first command adds Ollama with the `bge-m3` embedding model (~1 GB) for document search; the second also pulls a local chat model (`gpt-oss:20b`, ~14 GB, GPU or strong CPU recommended). Chat works once the download finishes and the status screen shows progress.

```bash
COMPOSE_PROFILES=local-ai make up
```

```bash
COMPOSE_PROFILES=local-ai ENABLE_LOCAL_GPT_OSS=true make up
```

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

### GET /api/v1/shares

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

Manage shares.

```APIDOC
## GET /api/v1/shares

### Description
Manage shares.

### Method
GET

### Endpoint
/api/v1/shares
```

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

### Configure Google AI via environment variables

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

Set any one of these three environment variables to configure Google AI. The first one set wins; the environment key is the bootstrap, and a key saved later in the admin UI is stored encrypted and wins over it.

```bash
GOOGLE_GEMINI_API_KEY=AIza…     # preferred name
# GEMINI_API_KEY=AIza…
# GOOGLE_API_KEY=AIza…

```

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

### Backup lifecycle hooks: pre-backup.sh and post-backup.sh

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

Run pre-backup.sh before capturing deploy/data to pause writers and create consistent snapshots, then run post-backup.sh after to resume services and keep seven completed portable backups by default. Restore uses the mirror-image pre-restore.sh and post-restore.sh scripts.

```bash
deploy/scripts/pre-backup.sh
# Capture deploy/data with your backup system.
deploy/scripts/post-backup.sh
```

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

### GET /api/v1/agents

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

Manage assistants.

```APIDOC
## GET /api/v1/agents

### Description
Manage assistants.

### Method
GET

### Endpoint
/api/v1/agents
```

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

### GET /api/v1/files

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

List files.

```APIDOC
## GET /api/v1/files

### Description
List files.

### Method
GET

### Endpoint
/api/v1/files
```

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

### GET /api/v1/chats

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

List chats.

```APIDOC
## GET /api/v1/chats

### Description
List chats.

### Method
GET

### Endpoint
/api/v1/chats
```

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

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

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

Saves an instruction or prompt topic.

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

### Description
Save an instruction (prompt topic).

### Method
POST

### Endpoint
/api.php

### Parameters
#### Form Data
- **action** (string) - Required - Must be `promptUpdate`.
- **prompt** (string) - Required - The prompt content.

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

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

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

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

### Start self-hosted SearXNG with docker compose

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

Run SearXNG with no host port, reachable only from the backend. Compose injects SEARXNG_BASE_URL=http://searxng:8080. If the URL is empty, the provider reports unavailable without breaking chat.

```bash
docker compose --profile searxng up -d   # no host port; reachable from the backend only
```

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

### Enable office profile with docker compose

Source: https://docs.synaplan.com/index.php/modules/office-convert

Starts the Collabora CODE container in the developer/evaluation stack. The Compose file defaults OFFICE_CONVERT_URL to http://collabora:9980, so no further configuration is needed. Expect about 2 GB of extra RAM for the container.

```bash
COMPOSE_PROFILES=office docker compose up -d      # or: docker compose --profile office up -d
```

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

### List modules via CLI (table and JSON)

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

Run these commands on a server without a browser to list modules. The first prints a table; the second outputs JSON with the same shape as the API. Both use docker compose exec backend.

```bash
docker compose exec backend php bin/console app:modules:list          # table
docker compose exec backend php bin/console app:modules:list --json   # same shape as the API below

```

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

### GET /api/v1/admin/groups

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

Admin endpoint for groups.

```APIDOC
## GET /api/v1/admin/groups

### Description
Admin endpoint for groups.

### Method
GET

### Endpoint
/api/v1/admin/groups
```

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

### Scaffold a plugin and commit

Source: https://docs.synaplan.com/presentation-developers.html?lang=en

Shows the plugin directory structure, the manifest.json content for a plugin named 'yours' with hooks and a route, and the git commit command to ship it.

```bash
$ ls plugins/
synasort/ synaads/ voice/ yours/
$ cat plugins/yours/manifest.json
{
  "name": "yours",
  "hooks": ["onMessage", "onIndex"],
  "route": "/api/v1/.../plugins/yours"
}
$ git commit -m "feat: ship it"
```

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

### Switch Synaplan Nextcloud app to Live environment

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

Commands to cleanly switch the Nextcloud app from Local to Live environment. Clears the local API key and URL settings, and in per-user mode deletes cached per-user keys and IDs so they are re-minted on the new server.

```bash
# 1. Point the app at Live and drop the Local dev settings
sudo -u www-data php occ config:app:set    synaplan_integration active_env --value live
sudo -u www-data php occ config:app:delete synaplan_integration api_key_local
sudo -u www-data php occ config:app:delete synaplan_integration synaplan_url_local

# 2. Per-user mode only: drop cached Synaplan keys/accounts that were minted on the
#    old server, so they are re-minted against the new one on next use
for uid in $(sudo -u www-data php occ user:list --output=json | jq -r 'keys[]'); do
  sudo -u www-data php occ user:setting "$uid" synaplan_integration synaplan_user_api_key --delete 2>/dev/null || true
  sudo -u www-data php occ user:setting "$uid" synaplan_integration synaplan_user_id     --delete 2>/dev/null || true
done

```

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

### Initialize and control the Synaplan widget

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

Import the Synaplan widget module and use the exposed methods to initialize, open, close, start a new chat, and destroy the widget. Call init() before using the other methods.

```javascript
import SynaplanWidget from 'https://web.synaplan.com/widget.js'

// Initialize the widget
SynaplanWidget.init({ widgetId: 'wdg_...' })

// Open the chat panel programmatically
SynaplanWidget.open()

// Close the chat panel
SynaplanWidget.close()

// Start a new chat conversation
SynaplanWidget.startNewChat()

// Tear down the widget completely (removes all DOM elements)
SynaplanWidget.destroy()

```

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

### SQL to enable GATE_WHATSAPP

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

Inserts or updates the BCONFIG row for the WhatsApp module gate. New installations seed every gate on; existing installations keep their current row. No restart is required; the next request reads the new value.

```sql
INSERT INTO BCONFIG (BOWNERID, BGROUP, BSETTING, BVALUE)
VALUES (0, 'MODULES', 'GATE_WHATSAPP', '1')
ON DUPLICATE KEY UPDATE BVALUE = '1';

```

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

### SynaplanWidget.init

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

Initializes the Synaplan Chat Widget with configuration options.

```APIDOC
## [POST] /api/v1/widgets/init

### Description
Initializes the Synaplan Chat Widget on the host page. This method must be called once with a configuration object to render the floating chat button and enable AI-powered chat.

### Method
POST

### Endpoint
/api/v1/widgets/init

### Parameters
#### Request Body
- **widgetId** (string) - Required - Widget ID from Manage → Channels → Chat widgets (e.g. `wdg_...`)
- **position** (string) - Optional - Button position: `bottom-right`, `bottom-left`, `top-right`, `top-left` (default: `'bottom-right'`)
- **primaryColor** (string) - Optional - Primary brand color (hex) (default: `'#007bff'`)
- **iconColor** (string) - Optional - Icon color on the button (hex) (default: `'#ffffff'`)
- **buttonIcon** (string) - Optional - Built-in icon: `chat`, `headset`, `help`, `robot`, `message`, `support` (default: `'chat'`)
- **buttonIconUrl** (string) - Optional - Custom icon URL (overrides `buttonIcon`)
- **defaultTheme** (string) - Optional - `light` or `dark` (default: `'light'`)
- **detectTheme** (boolean) - Optional - Auto-detect host page theme (default: `false`)
- **autoOpen** (boolean) - Optional - Open chat automatically on page load (default: `false`)
- **autoMessage** (string) - Optional - Initial greeting message (default: `'Hello! How can I help you today?'`)
- **widgetTitle** (string) - Optional - Title shown in chat header (default: `'Chat Support'`)
- **messageLimit** (number) - Optional - Maximum messages per session (default: `50`)
- **allowFileUpload** (boolean) - Optional - Enable file uploads (default: `false`)
- **fileUploadLimit** (number) - Optional - Max files per message (default: `3`)
- **maxFileSize** (number) - Optional - Max file size in MB (default: `10`)
- **lazy** (boolean) - Optional - Lazy-load Vue and chat UI on first interaction (default: `true`)
- **fullscreenMode** (boolean) - Optional - Start in fullscreen mode (default: `false`)
- **allowFullscreen** (boolean) - Optional - Allow users to toggle fullscreen (default: `false`)
- **hideButton** (boolean) - Optional - Hide the floating button (control via API only) (default: `false`)
- **apiUrl** (string) - Optional - Override the API base URL (auto-detected from script source)
- **externalUserId** (string) - Optional - External user ID for authenticated sessions
- **privacyPolicyUrl** (string) - Optional - Link to your privacy policy
- **allowedDomains** (string[]) - Optional - Restrict widget to specific domains (default: `[]`)

### Request Example
```json
{
  "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"
}
```

### Response
#### Success Response (200)
- **status** (string) - Success status
- **message** (string) - Success message

#### Response Example
```json
{
  "status": "success",
  "message": "Widget initialized"
}
```
```

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

### GET /api/v1/widgets

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

Manage your embeddable chat widgets.

```APIDOC
## GET /api/v1/widgets

### Description
Manage your embeddable chat widgets.

### Method
GET

### Endpoint
/api/v1/widgets
```

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

### Run tests with make test

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

Run the test suite. Use make test for all tests, or target backend (PHPUnit) or frontend (Vitest) individually.

```bash
make test                          # All tests (backend + frontend)
make -C backend test               # Backend only (PHPUnit)
make -C frontend test              # Frontend only (Vitest)
```

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

### GET /api/v1/rag/search

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

Search RAG knowledge base.

```APIDOC
## GET /api/v1/rag/search

### Description
Search RAG knowledge base.

### Method
GET

### Endpoint
/api/v1/rag/search
```

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

### GET /api/v1/widgets

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

Lists all widgets available to the authenticated user.

```APIDOC
## GET /api/v1/widgets

### Description
List all widgets.

### Method
GET

### Endpoint
/api/v1/widgets

### Response
#### Success Response (200)
- Returns a list of widgets.

#### Response Example
{
  "widgets": []
}
```

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

### Build frontend for production

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

Build the frontend for production. Use make -C frontend build for the Vue SPA and make -C frontend build-widget for the embeddable widget.

```bash
make -C frontend build             # Build the Vue SPA
make -C frontend build-widget      # Build the embeddable widget
```

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

### List Available Tools

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

Retrieves a list of available tools. Replace SESSION with the Mcp-Session-Id obtained during initialization.

```bash
curl -X POST https://web.synaplan.com/mcp \
     -H "X-API-Key: YOUR_SYNAPLAN_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -H "MCP-Protocol-Version: 2025-11-25" \
     -H "Mcp-Session-Id: SESSION" \
     -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
```

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

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

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

Retrieves the list of widgets for the authenticated user.

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

### Description
Get widgets. Requires authentication.

### Method
POST

### Endpoint
/api.php

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

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

### Response
#### Success Response (200)
- Returns a list of widgets.

#### Response Example
{
  "widgets": []
}
```

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

### GET /campaigns/{id}/download

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

Download the campaign as a ZIP file.

```APIDOC
## GET /campaigns/{id}/download

### Description
Download the campaign as a ZIP file.

### Method
GET

### Endpoint
/api/v1/user/{userId}/plugins/synaads/campaigns/{id}/download

### Parameters
#### Path Parameters
- **userId** (string) - Required - The ID of the user.
- **id** (string) - Required - The ID of the campaign.

### Response
#### Success Response (200)
- **file** (binary) - The ZIP file containing the campaign.

```

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

### Map IAP products to tiers with IAP_PRODUCT_* and IAP_STORE_PRICE_*

Source: https://docs.synaplan.com/index.php/modules/mobile-iap

Environment variables mapping IAP products to tiers and setting store prices. No defaults are provided; a forgotten product ID disables IAP loudly.

```plaintext
IAP_PRODUCT_PRO=com.example.app.pro.monthly
IAP_PRODUCT_TEAM=com.example.app.team.monthly
IAP_PRODUCT_BUSINESS=com.example.app.business.monthly

IAP_STORE_PRICE_PRO=24.99          # fixed EUR store price points shown in the app
IAP_STORE_PRICE_TEAM=64.99
IAP_STORE_PRICE_BUSINESS=129.99
IAP_PRICE_MARKUP_PERCENT=30        # fallback when a tier's store price is 0: web price + markup, snapped to x.99

```

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

### GET /api/v1/widgets/{id}

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

Retrieves details for a single widget by its ID.

```APIDOC
## GET /api/v1/widgets/{id}

### Description
Get details of a specific widget.

### Method
GET

### Endpoint
/api/v1/widgets/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The widget identifier.

### Response
#### Success Response (200)
- Returns the widget object.

#### Response Example
{
  "id": "wgt_abc123",
  "name": "New Support Chat Name",
  "isActive": true
}
```