System & Infrastructure (system.ts)

Master reference for SveltyCMS system operations — global settings, widget lifecycle, webhooks, AI services, and data importers.

4/12/2026

3 min read

Edit on GitHub

On this page

The System API is the foundational administrative layer of SveltyCMS. It coordinates the lifecycle of widgets, manages global configuration settings, handles service integrations like AI and Automations, and provides system health and telemetry monitoring.

⚡ Quick Reference

Component	HTTP Endpoint	Primary Method	Permission
Settings	`/api/settings`	`GET/POST`	`manage:system`
Widgets	`/api/widgets`	`GET/POST`	`manage:system`
Webhooks	`/api/webhooks`	`GET/POST`	`manage:system`
AI Services	`/api/ai`	`POST`	`manage:system`
Automations	`/api/automations`	`GET/POST`	`manage:system`
Importers	`/api/importer`	`POST`	`manage:system`
Health	`/api/system/health`	`GET`	Public

1. Global Settings & Preferences

SveltyCMS uses a hierarchical configuration system. Settings can be public (accessible by the frontend) or private (restricted to the backend).

Namespace Aliases: Both /api/settings and /api/system-settings resolve to this handler.

Public Settings: GET /api/settings/public — Returns essential configuration for the client app.
Public Stream: GET /api/settings/public/stream — SSE endpoint for real-time setting updates.
Tenant Settings: GET /api/settings/{group} — Retrieves settings for a specific domain (e.g., email, auth).
User Preferences: /api/system-preferences — Manages per-user UI settings like theme choice or dashboard layouts.

2. Widget Lifecycle

The 3-Pillar Widget System is managed via the widgets namespace.

List All: GET /api/widgets/list — Returns all installed and available widgets.
Activate/Deactivate: POST /api/widgets/activate — Toggles the runtime availability of a widget.

3. Webhooks & Integrations

Webhooks allow SveltyCMS to notify external systems about content changes or system events.

Create/Update: POST /api/webhooks — Saves a webhook with a target URL and event filters.
Test Webhook: POST /api/webhooks/{id}/test — Dispatches a dummy payload to verify connectivity.
Security: Every webhook delivery includes an X-Svelty-Signature (HMAC-SHA256) for verification.

4. AI & Automations

SveltyCMS features native AI integration and an automation engine for complex workflows.

AI Chat/Enrich: POST /api/ai/chat — Interacts with the configured LLM (OpenAI, Gemini, etc.) using the current content context.
Automations: /api/automations — Manage and trigger low-code workflows and event-driven tasks.

5. Data Importers

Migrate data from external sources or scaffold new environments.

Namespace Aliases: Both /api/importer and /api/import-data resolve to this handler.

Import Data: POST /api/import-data — Bulk inserts entries into a collection.
Smart Import: POST /api/importer/external — Automatically maps and fetches data from external CMS platforms.

6. The Mechanics

Consolidated Dispatcher

The system.ts handler acts as a master router, delegating specialized logic to internal services like webhookService, settingsService, and the automationEngine.

graph TD A[System API Handler] --> B[Settings Manager] A --> C[Widget Registry] A --> D[Webhook Service] A --> E[AI / Automation Engine] A --> F[CORS / Health Checks]

Resource Isolation

All system operations are strictly scoped to the tenantId resolved from the request context, ensuring that system configurations do not leak between tenants in a multi-tenant deployment.

Documentation