REST API Structure

Synaplan has migrated from an action-based API to a modern, RESTful architecture built on Symfony. All new endpoints follow standard HTTP methods and resource-based paths.

URL Structure

All API routes are prefixed with /api/v1/.

Data Formats

• Request Body: JSON (Content-Type: application/json) is preferred for most POST/PATCH requests. For file uploads, use multipart/form-data.
• Response Body: Always returns JSON.
• Errors: Standard HTTP status codes (400, 401, 403, 404, 500) with a JSON error object:

  {
    "error": "Error message description"
  }
  

Request Example (JSON)

Updating a widget configuration:

curl -X PATCH "https://web.synaplan.com/api/v1/widgets/wgt_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "New Support Chat Name",
       "isActive": true
     }'

Legacy REST Endpoints (api.php)

The legacy api.php action-based endpoints are still supported. Send requests as multipart/form-data with an action field.

action=messageNew – Send a chat message

curl -sS -X POST -F "action=messageNew" -F "message=Hello" https://web.synaplan.com/api.php

action=chatStream – Stream AI response (SSE)

• Anonymous widget or authenticated
• Body: lastIds (comma-separated IDs returned by messageNew) or again=1 with in_id

curl -N -X POST -F "action=chatStream" -F "lastIds=123" https://web.synaplan.com/api.php

action=againOptions – Get model options for re-run

action=messageAgain – Trigger context-aware rerun

action=snippetTranslate – Translate short text

• Authenticated
• Body: source_text, source_lang (default en), dest_lang

curl -sS -H "Authorization: Bearer $SYNAPLAN_API_KEY" -X POST \
  -F action=snippetTranslate \
  -F source_text="Hello, how are you?" \
  -F source_lang=en \
  -F dest_lang=de \
  https://web.synaplan.com/api.php

action=docSum – Summarize a document

action=ragUpload – Upload files for RAG

• Authenticated, files via files[]

Prompt endpoints

• promptLoad, promptUpdate, deletePrompt, getPromptDetails

File endpoints

• getMessageFiles (anon allowed), getFileGroups, changeGroupOfFile

action=getProfile – Get profile JSON

action=loadChatHistory – Recent chat messages

• Body: amount in {10,20,30}

Widget endpoints

• getWidgets, saveWidget, deleteWidget (authenticated)

API key endpoints

• getApiKeys, createApiKey, setApiKeyStatus, deleteApiKey (authenticated)

User endpoints

• userRegister, lostPassword (public)

Mail handler endpoints

• getMailhandler, saveMailhandler, mailOAuthStart, mailOAuthCallback, mailOAuthStatus, mailOAuthDisconnect, mailTestConnection

Detailed Endpoint List

For a complete list of all RESTful resources and their parameters, please refer to the Swagger documentation:

👉 Interactive API Reference