Settings API

Site settings live in config/site.json and are edited at System > Site Settings. They need the settings permission (read or update). The theme has its own endpoints, under Theme below.

GET /api/settings

Requires Bearer token + settings read permission.

The site settings. The SMTP password is always sent back empty.

// Response 200
{ "title": "My Site", "tagline": "...", "baseUrl": "https://example.com", "adminHome": "/",
  "smtp": { "host": "...", "pass": "", ... }, "footer": { ... }, "seo": { ... }, ... }

PUT /api/settings

Requires Bearer token + settings update permission.

Save settings. Send only what changes: top-level keys are merged into the stored settings, and objects such as smtp or footer are merged one level deep. An empty smtp.pass keeps the stored password. An unknown key is refused with 400, so a typo cannot be saved silently. The public pages' cache is cleared.

Key	What it is
title, tagline, description, logo, favicon	The site's name and identity
baseUrl	Site URL - an origin only (https://example.com, no path). Canonical links, the sitemap and password reset links are built on it.
adminHome	The admin screen #/ opens, e.g. /plugins/blog; empty for the Dashboard
smtp	Mail server: host, port, user, pass, secure, fromAddress, fromName
seo, footer, social, backToTop, cookieConsent, breadcrumbs, layoutOptions	The Site Settings tabs of the same names
theme, adminTheme, autoTheme, fontFamily, fontSize, adminBrand, locale, analytics, brand, url, baseTheme	Also accepted; most are set from Theme or kept for older sites

// Request body
{ "tagline": "Fresh bread daily", "smtp": { "port": 465, "secure": true } }
// Response 200
{ "success": true }
// Error 400
{ "error": "Unknown settings keys: siteName" }

POST /api/settings/test-email

Requires Bearer token + settings read permission.

Send a test email with the saved SMTP settings.

// Request body (optional - defaults to the From address)
{ "to": "alice@example.com" }
// Response 200
{ "success": true, "message": "Test email sent to alice@example.com" }
// Error 400
{ "error": "SMTP is not configured. Save your SMTP settings first." }

GET /api/settings/db-status

Requires Bearer token + settings read permission.

Whether any MongoDB connection is set up (config/connections.json).

// Response 200
{ "configured": true, "connections": ["default"] }

GET /api/settings/custom-css

Requires Bearer token + settings update permission.

The site-wide custom CSS (content/custom.css), which is inlined into every public page.

// Response 200
{ "css": "body { font-family: sans-serif; }" }

PUT /api/settings/custom-css

Requires Bearer token + settings update permission.

Replace the custom CSS (at most 100 KB). The public pages' cache is cleared.

// Request body
{ "css": "..." }
// Response 200
{ "success": true }

Theme

GET /api/theme

Requires Bearer token + theme read permission.

The site's theme settings (config/theme.json): the public and admin themes, day/night switching, fonts and any custom themes. PUT /api/theme (update permission) saves them, answering 400 with the problems if they do not validate. GET /api/theme/catalog lists the themes and colour tokens available, and GET /api/theme/themes/:id one theme's token values.