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

The OpenAI-compatible endpoints (/v1/chat/completions, /v1/models, /v1/audio/transcriptions) and the Anthropic-compatible /v1/messages gateway sit outside this prefix, directly under /v1 — see Interactive API (Swagger) and Claude Code.

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 PUT "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)

A small compatibility shim at POST /api.php still accepts the old action-based calls, so integrations written against the 1.x API keep working. Send requests as multipart/form-data with an action field. Only the actions below exist; every other 1.x action answers {"success":false,"error":"Unknown action: …","code":404} and has a /api/v1 replacement (see the Swagger UI). New integrations should not start on api.php.

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=messageGet – Fetch one message by id

action=againOptions – Get model options for re-run

action=ragUpload – Upload files for RAG

• Authenticated, files via files[]. Replacement: POST /api/v1/files/upload.

action=promptUpdate – Save an instruction (prompt topic)

action=getProfile – Get profile JSON

• Replacement: GET /api/v1/auth/me.

Widget endpoints

• getWidgets, saveWidget (authenticated). Replacement: /api/v1/widgets.

action=createApiKey – Create an API key (authenticated)

Account endpoints

• sendEmail, verifyEmail, wpWizardComplete (used by the WordPress onboarding wizard)

Removed from the shim (use /api/v1 instead): snippetTranslate, docSum (→ Summarize a document in chat or POST /api/v1/summary/generate), messageAgain (→ POST /api/v1/messages/again), loadChatHistory (→ GET /api/v1/messages/history), the prompt / file-group / mail-handler getters, deleteWidget, getApiKeys, setApiKeyStatus, deleteApiKey, userRegister, lostPassword.

Plugin Endpoints

Installed plugins expose their own endpoints under a per-user namespace:

/api/v1/user/{userId}/plugins/{name}/...

For example, POST /api/v1/user/1/plugins/synaads/campaigns creates a campaign with the Synaads plugin. Every plugin call is gated by the plugin's per-user enabled flag. See Plugins & Integrations for the full route lists.

Detailed Endpoint List

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

👉 Interactive API Reference